Elasticsearch API Specification

The Elasticsearch API design guidelines provide a set of best practices for creating HTTP APIs that are consistent and easy to consume. These guidelines are intended to support a growing number of API consumers and enable automated systems, such as automatic API documentation generation, to work effectively.

Key Principles:

• Guidelines, not hard rules: These are best practices distilled from experience. Deviations are permitted but should be accompanied by solid reasoning.
• Consistency: The primary goal is to ensure the Elastic product surface is predictable for users and compatible with automated tooling.
• Evolutionary approach: While aligning existing APIs with these principles is a goal, it is recognized as a gradual process.

The clients_schema_to_openapi utility converts the Elasticsearch API schema.json file into an OpenAPI version 3.0.3 specification. This is useful for generating OpenAPI-compliant documentation or client libraries from the core Elasticsearch API specification.

The conversion follows this pipeline:

1. TypeScript API generates the initial schema.json.
2. schema.json is processed into schema-no-generics.json.
3. schema-no-generics.json is then converted into the final openapi.json and serverless-openapi.json files.

To ensure enumerations work reliably across different programming languages, follow these rules:

1. Use String Values: Always represent enum members as strings.
2. Case Sensitivity: Values must be case-sensitive and maintain consistent casing.
3. Basic Characters: Use only basic characters in enum values.
4. Avoid Boolean Conflation: Do not mix booleans and enumerations. If an enum evolves from a boolean, do not simply add enum values to the boolean type. Instead, create a distinct enum or add a specific value like "disabled" to the enum to maintain type safety and backward compatibility.

The compiler uses a metamodel to define the structure of the JSON output. Key components of the modeling process include:

• modelType: A utility in compiler/model/utils.ts that recursively traverses types until they are modeled according to the metamodel.
• getNameSpace: A method used to determine the namespace of a declaration, which is particularly important when visiting extended classes.
• getAllBehaviors: A method that traverses all ancestors of a current class to find and pass down defined behaviors.

Avoid using unions directly within class definitions, as this is considered a code smell. Instead, create a named type alias to describe the union. This improves readability and reusability.

Incorrect (Inline Union):

class Foo {
  id: string | number
}

Correct (Type Alias):

class Foo {
  id: Id
}
type Id = string | number

Request and Response definitions must follow the namespace and endpoint structure of the API.

For example, the definitions for the indices.put_mapping API should be located in /specification/indices/put_mapping.

Requirements:

• Location: Follow the namespace/endpoint directory pattern.
• Naming: While the file name is flexible, the type itself must be named exactly Request or Response.

Behaviors are used to handle APIs that require special treatment based on the language. To implement a behavior, you must define it in two locations:

1. In the specification: Define the behavior in specification/__spec_utils/behaviors.ts.
2. In the compiler: Add the corresponding logic in compiler/model/utils.ts.

Note: If a behavior is defined in the specification but is missing from compiler/model/utils.ts, the compiler will throw an error.

For simple types, use the short TypeScript array notation. However, if the array contains complex types (such as a union), use the full Array<T> definition to maintain clarity.

Correct (Simple): bar: string[]

Correct (Complex/Union): bar: Array<string | number>

Incorrect (Complex/Union): bar: (string | number)[]

class Foo {
  bar: string[] // yay
  bar: (string | number)[] // nay
  bar: Array<string | number> // yay
}

Use the CommonCatQueryParameters behavior to implement the set of common query parameters specifically supported by all Cat APIs. Like standard query parameters, these are listed as a behavior because they can affect request structure.

Example usage:

class CatRequestBase extends RequestBase implements CommonCatQueryParameters {}

Dots (.) can be used as separators for nesting, but they are considered an alternate way to specify a nested structure rather than part of the name itself.

Requirement: If an API supports dotted notation, it must also allow the same structure via nested objects. Language clients typically only support nested object notation.

Equivalency Example:

// These are equivalent:
{
  "index.settings.number_of_shards": 1
}
{
  "index": {
    "settings": {
      "number_of_shards": 1
    }
  }
}

Note: Dotted keys only apply to API-specified structures. User-specified names (like field names) may contain dots without requiring nesting rules.