feat(specs): add OpenAPI spec for Monitoring API (#1683)

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

.github/.cache_version

@@ -1 +1 @@
-0.0.34
+0.0.35

.redocly.yaml

@@ -3,6 +3,7 @@ apis:
   analytics: specs/analytics/spec.yml
   ingestion: specs/ingestion/spec.yml
   insights: specs/insights/spec.yml
+  monitoring: specs/monitoring/spec.yml
   personalization: specs/personalization/spec.yml
   query-suggestions: specs/query-suggestions/spec.yml
   recommend: specs/recommend/spec.yml

clients/algoliasearch-client-javascript/yarn.lock

@@ -109,6 +109,19 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@algolia/monitoring@workspace:packages/monitoring":
+  version: 0.0.0-use.local
+  resolution: "@algolia/monitoring@workspace:packages/monitoring"
+  dependencies:
+    "@algolia/client-common": 5.0.0-alpha.73
+    "@algolia/requester-browser-xhr": 5.0.0-alpha.73
+    "@algolia/requester-node-http": 5.0.0-alpha.73
+    "@types/node": 18.16.18
+    rollup: 2.79.1
+    typescript: 5.0.4
+  languageName: unknown
+  linkType: soft
+
 "@algolia/predict@workspace:packages/predict":
   version: 0.0.0-use.local
   resolution: "@algolia/predict@workspace:packages/predict"

config/openapitools.json

@@ -75,6 +75,13 @@
           "packageName": "ingestion"
         }
       },
+      "javascript-monitoring": {
+        "output": "#{cwd}/clients/algoliasearch-client-javascript/packages/monitoring",
+        "additionalProperties": {
+          "packageVersion": "1.0.0-alpha.1",
+          "packageName": "monitoring"
+        }
+      },
       "java-search": {
         "output": "#{cwd}/clients/algoliasearch-client-java-2"
       },
@@ -96,6 +103,9 @@
       "java-query-suggestions": {
         "output": "#{cwd}/clients/algoliasearch-client-java-2"
       },
+      "java-monitoring": {
+        "output": "#{cwd}/clients/algoliasearch-client-java-2"
+      },
       "php-search": {
         "output": "#{cwd}/clients/algoliasearch-client-php"
       },
@@ -117,6 +127,9 @@
       "php-query-suggestions": {
         "output": "#{cwd}/clients/algoliasearch-client-php"
       },
+      "php-monitoring": {
+        "output": "#{cwd}/clients/algoliasearch-client-php"
+      },
       "go-analytics": {
         "output": "#{cwd}/clients/algoliasearch-client-go",
         "additionalProperties": {
@@ -165,6 +178,12 @@
           "packageName": "predict"
         }
       },
+      "go-monitoring": {
+        "output": "#{cwd}/clients/algoliasearch-client-go",
+        "additionalProperties": {
+          "packageName": "monitoring"
+        }
+      },
       "kotlin-search": {
         "output": "#{cwd}/clients/algoliasearch-client-kotlin"
       },
@@ -192,6 +211,9 @@
       "kotlin-ingestion": {
         "output": "#{cwd}/clients/algoliasearch-client-kotlin"
       },
+      "kotlin-monitoring": {
+        "output": "#{cwd}/clients/algoliasearch-client-kotlin"
+      },
       "dart-algoliasearch": {
         "output": "#{cwd}/clients/algoliasearch-client-dart/packages/algoliasearch",
         "additionalProperties": {

generators/src/main/java/com/algolia/codegen/AlgoliaJavaGenerator.java

@@ -125,6 +125,13 @@ public String toEnumVarName(String value, String datatype) {
       return super.toEnumVarName(value, datatype);
     }
 
+    // In some cases, the API might accept characters instead of the textual notation, we will
+    // replace it internally so that it doesn't output the character itself.
+    switch (value) {
+      case "*":
+        return "ALL";
+    }
+
     if (!value.matches("[A-Z0-9_]+")) {
       // convert camelCase77String to CAMEL_CASE_77_STRING
       return value.replaceAll("-", "_").replaceAll("(.+?)([A-Z]|[0-9])", "$1_$2").toUpperCase(Locale.ROOT);

scripts/buildSpecs.ts

@@ -70,8 +70,15 @@ async function transformBundle({
 
       // Checks that specified tags are well defined at root level
       for (const tag of docMethod.tags) {
-        if (tag === clientName || (alias && tag === alias)) {
-          return;
+        if (tag === clientName) {
+          throw new Error(
+            `Tag name "${tag}" must be different from client name ${clientName}`
+          );
+        }
+        if (alias && tag === alias) {
+          throw new Error(
+            `Tag name "${tag} must be different from alias ${alias}`
+          );
         }
 
         const tagExists = tagsDefinitions

scripts/ci/utils.ts

@@ -31,7 +31,7 @@ export async function getNbGitDiff({
   return parseInt(
     (
       await run(
-        `git diff --shortstat ${branch}${checkHead} -- ${path} | wc -l`,
+        `git add -N . && git diff --shortstat ${branch}${checkHead} -- ${path} | wc -l`,
         { cwd }
       )
     ).trim(),

scripts/cts/generate.ts

@@ -39,7 +39,9 @@ export async function ctsGenerateMany(generators: Generator[]): Promise<void> {
     }
 
     if (lang === 'javascript') {
-      await run('yarn install', { cwd: 'tests/output/javascript' });
+      await run('YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn install', {
+        cwd: 'tests/output/javascript',
+      });
     }
 
     await formatter(lang, toAbsolutePath(`tests/output/${lang}`));

specs/monitoring/common/enums.yml

@@ -0,0 +1,64 @@
+Metric:
+  type: string
+  enum:
+    - avg_build_time
+    - ssd_usage
+    - ram_search_usage
+    - ram_indexing_usage
+    - cpu_usage
+    - '*'
+  example: '*'
+
+Period:
+  type: string
+  enum:
+    - minute
+    - hour
+    - day
+    - week
+    - month
+  example: week
+
+Region:
+  title: region
+  type: string
+  description: The region where the cluster is located.
+  enum:
+    - au
+    - br
+    - ca
+    - de
+    - eu
+    - hk
+    - in
+    - jp
+    - sg
+    - uae
+    - uk
+    - usc
+    - use
+    - usw
+    - za
+  example: de
+
+Status:
+  title: status
+  type: string
+  description: Status of the cluster.
+  enum:
+    - operational
+    - degraded_performance
+    - partial_outage
+    - major_outage
+
+ServerStatus:
+  title: status
+  type: string
+  enum:
+    - PRODUCTION
+
+Type:
+  title: type
+  type: string
+  enum:
+    - cluster

specs/monitoring/common/parameters.yml

@@ -0,0 +1,38 @@
+# path
+Clusters:
+  name: clusters
+  in: path
+  required: true
+  description: Subset of clusters, separated by comma.
+  schema:
+    # The `correct` (?) schema should be type array/items string,
+    # But the SDK generator expects a string, because it can't replace a list of strings in the URL.
+    type: string
+    example: 'c1-de,c2-de,c3-de'
+
+MetricInPath:
+  name: metric
+  in: path
+  required: true
+  description: |
+    Metric to report.
+
+    For more information about the individual metrics, see the response.
+    To include all metrics, use `*` as the parameter.
+  schema:
+    $ref: './enums.yml#/Metric'
+
+PeriodInPath:
+  name: period
+  in: path
+  required: true
+  description: |
+    Period over which to aggregate the metrics:
+
+    - `minute`. Aggregate the last minute. 1 data point per 10 seconds.
+    - `hour`. Aggregate the last hour. 1 data point per minute.
+    - `day`. Aggregate the last day. 1 data point per 10 minutes.
+    - `week`. Aggregate the last week. 1 data point per hour.
+    - `month`. Aggregate the last month. 1 data point per day.
+  schema:
+    $ref: './enums.yml#/Period'

specs/monitoring/common/responses/BadRequestResponse.yml

@@ -0,0 +1,13 @@
+description: Bad Request.
+content:
+  application/json:
+    schema:
+      type: object
+      additionalProperties: false
+      properties:
+        reason:
+          type: string
+    examples:
+      BadRequest:
+        value:
+          reason: Unknown servers

specs/monitoring/common/responses/ForbiddenResponse.yml

@@ -0,0 +1,13 @@
+description: Forbidden
+content:
+  application/json:
+    schema:
+      type: object
+      additionalProperties: false
+      properties:
+        reason:
+          type: string
+    examples:
+      Forbidden:
+        value:
+          reason: invalid credentials

specs/monitoring/common/responses/IncidentsResponse.yml

@@ -0,0 +1,27 @@
+description: OK
+content:
+  application/json:
+    schema:
+      title: IncidentsResponse
+      type: object
+      properties:
+        incidents:
+          type: object
+          additionalProperties:
+            x-additionalPropertiesName: cluster
+            $ref: '../schemas/Incidents.yml'
+    examples:
+      success:
+        value:
+          incidents:
+            m134-de:
+              - t: 1687441685000
+                v:
+                  title: 'Incident on cluster m134-de: Everything operating normally.'
+                  status: operational
+              - t: 1687441579000
+                v:
+                  title: >-
+                    Incident on cluster m134-de: We are encountering a major
+                    issue that impact all API calls.
+                  status: major_outage

specs/monitoring/common/responses/IndexingResponse.yml

@@ -0,0 +1,27 @@
+description: OK
+content:
+  application/json:
+    schema:
+      title: IndexingTimeResponse
+      type: object
+      properties:
+        metrics:
+          type: object
+          additionalProperties: false
+          properties:
+            indexing:
+              additionalProperties:
+                x-additionalPropertiesName: times
+                $ref: '../schemas/Time.yml'
+    examples:
+      Success:
+        value:
+          metrics:
+            indexing:
+              c16-de:
+                - t: 1688056200000
+                  v: 1562
+                - t: 1688056800000
+                  v: 1637
+                - t: 1688057400000
+                  v: 1754

specs/monitoring/common/responses/InfrastructureAPIUnauthorized.yml

@@ -0,0 +1,15 @@
+description: Unauthorized
+content:
+  application/json:
+    schema:
+      type: object
+      additionalProperties: false
+      properties:
+        reason:
+          type: string
+    examples:
+      Unauthorized:
+        value:
+          reason: >-
+            The infrastructure usage API is only available on Enterprise plans.
+            Please contact enterprise@algolia.com for more detail.