Skip to main content
info

Algolia's API specs follow the OpenAPI specification, version 3.1.

Starting from an existing specification really eases the contribution process and is recommended (e.g. search)

Do not edit the files in specs/bundled they are the generated from the manually written specifications, and only used to generate API clients.

caution

A specification is used to generate the API client, its tests and code snippets, but is most importantly served by the Algolia public documentation, please read our API Documentation guidelines to properly document your specification.

Structure your specification

Each API specification follows a consistent structure.

specs/common/​

This common directory contains schemas and parameters that are common to multiple Algolia APIs, for example: search parameters or indexName definitions.

specs/<apiName>/​

Each API must be contained in its own directory, for example: the Search API.

specs/<apiName>/spec.yml​

This file is the main entrypoint of your specification and should describe your API, including the servers, securitySchemes and paths properties.

specs/<apiName>/common/​

This directory contains schemas and parameters that are common to your API. For schemas that are shared between multiple APIs please use the global specs/common directory.

specs/<apiName>/paths/​

This directory contains the descriptions of the endpoints of your API. The paths themselves are defined in the spec.yml file.

specs/<apiName>/paths/<operation>.yml​

Operations are endpoints combined with an HTTP method (GET, POST, etc.). Each operation must have a unique operationID property. Operations for the same endpoint may share the same file, for example, the GET and DELETE request for the same endpoint.

Filenames​

Follow these conventions:

  • If the file only contains one operation, use <operationId>.yml as filename.
  • If the file contains multiple operations, use a more generic name, for example rule.yml for the GET, PUT, and DELETE request for a rule.
Summaries and descriptions​

Every operation must have a summary and description property (they will be used in the generated API clients, and the Algolia documentation). For information about documenting operations, see Operation summaries and Operation descriptions.

Access Control Lists (ACL)​

Each operation should include an x-acl property to document the ACL required to make the request.

The x-acl property is an array of strings, the allowed values are: search, browse, addObject, deleteObject, listIndexes, deleteIndex, settings, editSettings, analytics, recommendation, usage, logs, setUnretrievableAttributes, admin. For operations that require the admin API key, use admin

Complex objects​

The following objects must not be inlined, but referenced with $ref:

  • Nested arrays
  • Nested objects
  • oneOf
  • allOf
  • enum

This is required for accurate naming of the generated code objects. It also improves the readability of the specs.

Properties and parameters​

  • Create separate objects and reference them for complex objects.

  • The format parameter for strings isn't supported.

  • For nullable properties, use the following syntax:

    nullableProp:
      default: null
      oneOf:
        - type: string
          description: Some value
        - type: 'null'
          description: The single quotes are required.

For information about documenting properties and parameters, see Properties and parameters.

CLI Commands​

Use the CLI to generate build your specs:

Troubleshooting​

Explicit names for request bodies​

Detailed issue

In some cases, the generated name for the requestBody property might be wrong. This can happen in these cases:

To provide a name for the request body, add the x-codegen-request-body-name property to the root of the operation's spec file.

For an example, see pull request #896.

Send additional options to the templates​

To send additional information to the generators, you can add properties starting with x- to the root level of your spec. These are available in the templates as part of the vendorExtensions object.

For an example, see search.yml