fix(specs): usage api (#2954)

Co-authored-by: Clément Vannicatte <vannicattec@gmail.com>

specs/usage/common/schemas/responses.yml

@@ -1,5 +1,5 @@
 Success:
-  description: Success.
+  description: OK
   content:
     application/json:
       schema:
@@ -12,39 +12,17 @@ Success:
               properties:
                 t:
                   type: integer
-                  description: >
-                    [Unix timestamp](https://www.unixtimestamp.com/) (in milliseconds).
+                  description: Timestamp in milliseconds in Unix epoch time.
                   example: 1455451200000
                 v:
-                  description: |
-                    Depending on the statistic, the type of this value (`v`) differs.
-                    Most statistics return integer values.
-
-                    `degraded_queries_*`, `max_qps`, and `used_search_capacity` are returned as maps of server name strings to integers.
-
-                    `region_*` statistics return strings (regions).
+                  description: Value of the statistics.
                   $ref: '#/statisticValue'
 
 statisticValue:
   oneOf:
     - type: integer
+      description: Value of the metric.
     - type: object
-      properties:
-        serverName:
-          type: string
-        value:
-          type: integer
-    - type: string
-
-MissingAuthorization:
-  description: Authorization information is missing or invalid.
-
-IndexNotFound:
-  description: |
-    Index not found.
-
-    If `index` has been correctly defined, this error message means that no data was found in the given time range.
-    The time range may lie outside the [data retention period](https://support.algolia.com/hc/en-us/articles/4406975230993-Can-I-extend-the-retention-period-of-the-analytics-data-).
-
-StatisticNotFound:
-  description: Metric not found.
+      additionalProperties:
+        type: integer
+        description: Value per server or region of the metric.

specs/usage/common/schemas/statistic.yml

@@ -0,0 +1,87 @@
+Statistic:
+  type: string
+  enum:
+    - '*'
+    - search_operations
+    - total_search_operations
+    - total_search_requests
+    - queries_operations
+    - multi_queries_operations
+    - acl_operations
+    - total_acl_operations
+    - get_api_keys_operations
+    - get_api_key_operations
+    - add_api_key_operations
+    - update_api_key_operations
+    - delete_api_key_operations
+    - list_api_key_operations
+    - indexing_operations
+    - total_indexing_operations
+    - browse_operations
+    - clear_index_operations
+    - copy_move_operations
+    - delete_index_operations
+    - get_log_operations
+    - get_settings_operations
+    - set_settings_operations
+    - list_indices_operations
+    - wait_task_operations
+    - record_operations
+    - total_records_operations
+    - add_record_operations
+    - batch_operations
+    - delete_by_query_operations
+    - delete_record_operations
+    - get_record_operations
+    - partial_update_record_operations
+    - update_record_operations
+    - synonym_operations
+    - total_synonym_operations
+    - batch_synonym_operations
+    - clear_synonym_operations
+    - delete_synonym_operations
+    - get_synonym_operations
+    - query_synonym_operations
+    - update_synonym_operations
+    - rule_operations
+    - total_rules_operations
+    - batch_rules_operations
+    - clear_rules_operations
+    - delete_rules_operations
+    - get_rules_operations
+    - save_rules_operations
+    - search_rules_operations
+    - total_recommend_requests
+    - total_write_operations
+    - total_read_operations
+    - total_operations
+    - querysuggestions_total_search_operations
+    - querysuggestions_total_search_requests
+    - querysuggestions_total_acl_operations
+    - querysuggestions_total_indexing_operations
+    - querysuggestions_total_records_operations
+    - querysuggestions_total_synonym_operations
+    - querysuggestions_total_rules_operations
+    - querysuggestions_total_write_operations
+    - querysuggestions_total_read_operations
+    - querysuggestions_total_operations
+    - avg_processing_time
+    - 90p_processing_time
+    - 99p_processing_time
+    - queries_above_last_ms_processing_time
+    - records
+    - data_size
+    - file_size
+    - max_qps
+    - region_max_qps
+    - total_max_qps
+    - used_search_capacity
+    - avg_used_search_capacity
+    - region_used_search_capacity
+    - region_avg_used_search_capacity
+    - total_used_search_capacity
+    - total_avg_used_search_capacity
+    - degraded_queries_ssd_used_queries_impacted
+    - degraded_queries_ssd_used_seconds_impacted
+    - degraded_queries_max_capacity_queries_impacted
+    - degraded_queries_max_capacity_seconds_impacted

specs/usage/paths/statistic.yml

@@ -1,11 +1,8 @@
 get:
   operationId: getUsage
-  summary: Get usage.
+  summary: Retrieve usage information.
   description: |
-    Returns usage statistics over a specified period.
-
-    The specified period must be within the last 90 days.
-    However, the period of [data retention can be extended](https://support.algolia.com/hc/en-us/articles/4406975230993-Can-I-extend-the-retention-period-of-the-analytics-data-) to a maximum of 365 days.
+    Retrieves usage statistics evaluated over a specified period.
   parameters:
     - $ref: '../common/parameters.yml#/statisticParameter'
     - $ref: '../common/parameters.yml#/startDateParameter'
@@ -17,10 +14,10 @@ get:
     '400':
       $ref: '../../common/responses/InvalidRequest.yml'
     '401':
-      $ref: '../common/schemas/responses.yml#/MissingAuthorization'
+      $ref: '../../common/responses/Unauthorized.yml'
     '403':
       $ref: '../../common/responses/Forbidden.yml'
     '404':
-      $ref: '../common/schemas/responses.yml#/IndexNotFound'
+      $ref: '../../common/responses/IndexNotFound.yml'
     '422':
-      $ref: '../common/schemas/responses.yml#/StatisticNotFound'
+      $ref: '../../common/responses/UnprocessableEntity.yml'

specs/usage/paths/statisticIndex.yml

@@ -1,14 +1,11 @@
 get:
   operationId: getIndexUsage
-  summary: Get usage for an index.
+  summary: Retrieve usage information for one index.
   description: |
-    Returns index usage statistics over a specified period.
-
-    The specified period must be within the last 90 days.
-    However, the period of [data retention can be extended](https://support.algolia.com/hc/en-us/articles/4406975230993-Can-I-extend-the-retention-period-of-the-analytics-data-) to a maximum of 365 days.
+    Retrieves the selected usage statistics for one index.
   parameters:
     - $ref: '../common/parameters.yml#/statisticParameter'
-    - $ref: '../common/parameters.yml#/indexParameter'
+    - $ref: '../../common/parameters.yml#/IndexName'
     - $ref: '../common/parameters.yml#/startDateParameter'
     - $ref: '../common/parameters.yml#/endDateParameter'
     - $ref: '../common/parameters.yml#/granularityParameter'
@@ -18,10 +15,10 @@ get:
     '400':
       $ref: '../../common/responses/InvalidRequest.yml'
     '401':
-      $ref: '../common/schemas/responses.yml#/MissingAuthorization'
+      $ref: '../../common/responses/Unauthorized.yml'
     '403':
       $ref: '../../common/responses/Forbidden.yml'
     '404':
-      $ref: '../common/schemas/responses.yml#/IndexNotFound'
+      $ref: '../../common/responses/IndexNotFound.yml'
     '422':
-      $ref: '../common/schemas/responses.yml#/StatisticNotFound'
+      $ref: '../../common/responses/UnprocessableEntity.yml'

specs/usage/spec.yml

@@ -2,26 +2,61 @@ openapi: 3.0.2
 info:
   title: Usage API
   description: |
-    API to retrieve usage statistics for HTTP requests made to Algolia applications.
+    The Usage API gives you access to statistics about all requests made to your Algolia applications.
 
-    Use the [Usage API key](https://dashboard.algolia.com/account/api-keys/) for authentication.
+    # Base URL
+
+    The base URL for requests to the Usage API is:
+
+    - `https://usage.algolia.com`
+
+    **All requests must use HTTPS.**
+
+    # Authentication
+
+    To authenticate your API requests, add these headers:
+
+    <dl>
+    <dt><code>x-algolia-application-id</code></dt>
+    <dd>Your Algolia application ID.</dd>
+    <dt><code>x-algolia-api-key</code></dt>
+    <dd>The Usage API key.</dd>
+    </dl>
+
+    You can find your application ID and Usage API key in the [Algolia dashboard](https://dashboard.algolia.com/account).
+
+    # Response status and errors
+
+    The Usage API returns JSON responses.
+    Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.
+
+    Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status.
+    Error responses have a `message` property with more information.
+
+    # Version
+
+    The current version of the Usage API is version 1, as indicated by the `/1/` in each endpoint's URL.
   version: 1.0.0
-  contact:
-    name: Algolia Usage API
-    url: 'https://www.algolia.com/doc/rest-api/usage/'
 components:
   securitySchemes:
-    BasicAuth:
-      type: http
-      scheme: basic
+    appId:
+      $ref: '../common/securitySchemes.yml#/appId'
+    apiKey:
+      $ref: '../common/securitySchemes.yml#/apiKey'
 servers:
-  - url: 'https://usage.algolia.com/1/usage'
-  - url: 'https://usage-dev.algolia.com/1/usage'
-  - url: 'http://localhost:8000/1/usage'
+  - url: 'https://usage.algolia.com'
+    description: Base URL of the Usage API.
+  - url: 'https://usage-dev.algolia.com'
+    description: Base URL for the development version of the Usage API (Algolia employees only).
 security:
-  - BasicAuth: []
+  - appId: []
+    apiKey: []
+tags:
+  - name: usage
+    x-displayName: Usage statistics
+    description: Get various metrics related to the usage of your Algolia applications.
 paths:
-  /{statistic}:
+  /1/usage/{statistic}:
     $ref: 'paths/statistic.yml'
-  /{statistic}/{index}:
+  /1/usage/{statistic}/{indexName}:
     $ref: 'paths/statisticIndex.yml'