Updated documentation (elastic#81)

Author: delvedor

README.md

@@ -184,13 +184,6 @@ Namespaced APIs can be validated in the same way, for example:
 ./run-validations.sh --api cat.health --request
 ```
 
-### Where do I see the test?
-
-Everytime you run the `run-validations` script, a series of test will be generated and dumped on disk.
-You can find them in `clients-flight-recorder/scripts/types-validator/workbench`.
-The content of this folder is a series of recorded responses from Elasticsearch wrapped inside an helper
-that verifies if the type definiton is correct.
-
 ## Custom types
 
 The goal of the specification is to be used by different languages, from dynamically typed to statically typed.
@@ -345,9 +338,7 @@ propertyOptional?: string
 
 ### A definition is missing, how do I add it?
 
-All the definitons are in the [`specifications/specs`](./specifications/specs) folder, you should explore its content and find the
-most approriate place where to add the new defintion. You can either create a new file or update an existing one.
-If possible, try to reuse existing type definitions (eg `Indices` instead of `string`).
+See [here](./docs/add-new-api.md).
 
 ### A definition is not correct, how do I fix it?
 
@@ -356,9 +347,7 @@ you can find above how to run the validation of the spec.
 
 ### An endpoint is missing, how do I add it?
 
-All the endpoint definitons are inside `specifications/specs/_json_spec` folder, which contains a series of
-JSON files taken directly from the Elasticsearch rest-api-spec.
-You should copy from there the missing endpoint and add it here.
+See [here](./docs/add-new-api.md).
 
 ### An endpoint definition is not correct, how do I fix it?
 
@@ -382,6 +371,13 @@ cd client-flight-recorder
 git pull
 ```
 
+### Where do I find the generated test?
+
+Everytime you run the `run-validations` script, a series of test will be generated and dumped on disk.
+You can find them in `clients-flight-recorder/scripts/types-validator/workbench`.
+The content of this folder is a series of recorded responses from Elasticsearch wrapped inside an helper
+that verifies if the type definiton is correct.
+
 ### Which editor should I use?
 
 Any editor is fine, but to have a better development experience it should be configured
@@ -390,7 +386,7 @@ to work with TypeScript. [Visual Studio Code](https://code.visualstudio.com/) an
 
 ### Is there a complete example of the process?
 
-Yes, take a look [here](./validation-example.md).
+Yes, take a look [here](./docs/validation-example.md).
 
 ### realpath: command not found
 

docs/add-new-api.md

@@ -0,0 +1,113 @@
+# How to add a new API
+
+It might happen that a new API in Elasticsearch is not yet defined
+in this repository, or we do have an endpoint definition in [`/specification/specs/_json_spec`](../specification/specs/_json_spec)
+but we don't have a type definition for it.
+In this document you will see how to add a new endpopint and how to add a new endpoint definition.
+
+**NOTE:** Currenlty we are following the work on the `7.x` release line.
+
+## How to add a new endpoint
+
+Add a new endpoint is straightforward, you only need to copy-paste the json rest-api-spec defintion
+from the Elasticsearch repository inside [`/specification/specs/_json_spec`](../specification/specs/_json_spec)
+and you are good to go.
+
+You can find the rest-api-spec definitions [here](https://github.com/elastic/elasticsearch/tree/7.x/rest-api-spec/src/main/resources/rest-api-spec/api)
+or [here](https://github.com/elastic/elasticsearch/tree/7.x/x-pack/plugin/src/test/resources/rest-api-spec/api).
+
+## How to add the definition of an endpoint
+
+Once you have added a new endpoint definition, the next step is to add its type definition.
+First of all, you should find the most approariate place inside [`/specification/specs`](../specification/specs)
+where to put the new definition. The content of [`/specification/specs`](../specification/specs)
+tryied to mimic the Elasticsearch online documentation, so you can use it as inspiration.
+For example, the index document defintion can be found in [`/specification/specs/document/single/index`](../specification/specs/document/single/index).
+
+Once you have found the best place for the new definition, you should create a new file for it.
+The filename should be the same of the type definition you are writing, for example:
+
+```ts
+// IndexRequest.ts
+class IndexRequest {}
+```
+
+```ts
+// IndexResponse.ts
+class IndexResponse {}
+```
+
+Try to use less files as possible, for example there is no need to create a custom file for an enum,
+you can define it in the same file where it's used, unless is a commonly used type.
+
+### Add the endpoint request definition
+
+Request definitions are slighly different from other definitions.
+A request definition should contains three top level keys:
+
+- `path_parts`: the path parameters (eg: `indices`, `id`...)
+- `query_parameters`: the query parameters (eg: `timeout`, `pipeline`...)
+- `body`: the body parameters (eg: `query` or user defined entities)
+
+Finally there should be a decorator to inform the compiler that this is a endpoint request definition.
+The value of the decorator should be the endpoint name as it's defined in the json spec (eg: `search`, `indices.create`...).
+Following you can find a template valid for any request definition.
+
+```ts
+@rest_spec_name("endpoint.name")
+class EndpointRequest extends RequestBase {
+  path_parts?: {
+
+  };
+  query_parameters?: {
+
+  };
+  body?: {
+
+  };
+}
+```
+
+In some cases, the request could take one or more generics, in such case the definition will be:
+```ts
+@rest_spec_name("endpoint.name")
+class EndpointRequest<Generic> extends RequestBase {
+  path_parts?: {
+
+  };
+  query_parameters?: {
+
+  };
+  body?: {
+
+  };
+}
+```
+And the generic will be used somewhere inside the definition.
+There are cases where the generic might be the entire body, see [`IndexRequest`](../specification/specs/document/single/index/IndexRequest.ts).
+
+### Add the endpoint response definition
+
+Responses definitions should always be defined **after** a request definition,
+otherwise the compiler will not pick them up. It is required that the response
+definition has the same name as the request definition aside from the `Response` suffix.
+
+For example the response definition for `ClusterHealthRequest` will be named `ClusterHealthResponse`.
+Following you can find a template valid for any response definition.
+
+```ts
+class EndpointResponse extends ResponseBase {
+
+}
+```
+
+As you can see, for responses there are no custom top level keys, as the
+response definition represents the body of a succesful response.
+
+In some cases, the response could take one or more generics, in such case the definition will be:
+```ts
+class EndpointResponse<Generic> extends ResponseBase {
+
+}
+```
+And the generic will be used somewhere inside the definition.