update requests to use interfaces and move to jsDoc

docs/add-new-api.md

@@ -29,7 +29,7 @@ The filename should be the same of the type definition you are writing, for exam
 
 ```ts
 // IndexRequest.ts
-class IndexRequest {}
+interface IndexRequest {}
 ```
 
 ```ts
@@ -43,21 +43,27 @@ you can define it in the same file where it's used, unless is a commonly used ty
 ### Add the endpoint request definition
 
 Request definitions are slighly different from other definitions.
-A request definition should contains three top level keys:
+A request definition is an interface and 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 (`rest_spec_name`) 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`...).
-You should also add another decorator (`since`) to track the version of Elasticsearch where this API has been introduced.
+Furthermore, every request definition **must** contain three JS Doc tags:
+
+- `@rest_spec_name`: the API name (eg: `search`, `indices.create`...).
+- `@since`: the version of Elasticsearch when the API has been introduced (eg: `7.7.0`)
+- `@stability`: the API stability, one of `experimental`, `beta`, `stable`
+
 Following you can find a template valid for any request definition.
 
 ```ts
-@rest_spec_name('endpoint.name')
-@since('1.2.3')
-class EndpointRequest extends RequestBase {
+ /*
+ * @rest_spec_name endpoint.name
+ * @since 1.2.3
+ * @stability TODO
+ */
+interface EndpointRequest extends RequestBase {
   path_parts?: {
 
   };
@@ -72,9 +78,12 @@ class EndpointRequest extends RequestBase {
 
 In some cases, the request could take one or more generics, in such case the definition will be:
 ```ts
-@rest_spec_name('endpoint.name')
-@since('1.2.3')
-class EndpointRequest<Generic> extends RequestBase {
+ /*
+ * @rest_spec_name endpoint.name
+ * @since 1.2.3
+ * @stability TODO
+ */
+interface EndpointRequest<Generic> extends RequestBase {
   path_parts?: {
 
   };
@@ -113,4 +122,4 @@ class EndpointResponse<Generic> extends ResponseBase {
 
 }
 ```
-And the generic will be used somewhere inside the definition.
+And the generic will be used somewhere inside the definition.

docs/behaviors.md

@@ -18,7 +18,7 @@ We therefore document the requirement to behave like a dictionary for unknown pr
 class IpRangeBucket implements AdditionalProperties<AggregateName, Aggregate> {}
 ```
 
-## ArrayResponse
+## ArrayResponseBase
 
 A response formatted as an array of records.
 Some languages can't represent this easily and need to wrap the
@@ -27,7 +27,7 @@ array inside an object.
 ```ts
 class CatAliasesResponse
   extends ResponseBase
-  implements ArrayResponse<CatAliasesRecord> {}
+  implements ArrayResponseBase<CatAliasesRecord> {}
 ```
 
 ## EmptyResponseBase
@@ -40,4 +40,24 @@ to define how those should be represented.
 class DocumentExistsResponse
   extends ResponseBase
   implements EmptyResponseBase {}
+```
+
+## CommonQueryParameters
+
+Implements a set of common query parameters all API's support.
+Since these can break the request structure these are listed explicitly as a behavior.
+Its up to individual clients to define support although `error_trace` and `pretty` are
+recommended as a minimum.
+
+```ts
+class RequestBase implements CommonQueryParameters {}
+```
+
+## CommonCatQueryParameters
+
+Implements a set of common query parameters all Cat API's support.
+Since these can break the request structure these are listed explicitly as a behavior.
+
+```ts
+class CatRequestBase extends RequestBase implements CommonCatQueryParameters {}
 ```