OpenAPI Specification

The OpenAPI Specification (formally known as Swagger specification) is a standard to describe REST APIs in a human and computer readable format and allow several features like interactive documentation and automated client generation.

GET /__api__

Returns the OpenAPI description for the running instance of Kinto on JSON format.

Important

Getting the description from this endpoint is the only way to get the full description for the running instance. The description returned is based on a swagger.yaml valid OpenAPI description file on the root of the Kinto python package, but which lacks some instance specific definitions that are updated on runtime.

Known limitations

OpenAPI 2.0 currently doesn’t support some features that are present on Kinto API. Some known limitations are:

  1. Lack of validation on OR clauses (e.g. provide data or permissions in PATCH operations), which are trated as non-required on the description. This is more critical when setting Batch operations, which all the fields should be either defined on each request on the requests array or on the default object.
  2. No support for query filters on properties. Only named parameters are accepted on OpenAPI 2.0, so these are not included on the specification.
  3. Optional response headers are not supported, as required for Backoff signs. On the specification, the Backoff field is only listed as a response header on default responses, that should be raised with HTTP 5xx errors.
  4. Collection defined schemas fields are not validated because they accept any JSON Schema definition, which may be too complex to be handled by an OpenAPI description. Only the type of the field is checked as a valid JSON object.

Important

The specifications used for loose schemas (objects that accept extra attributes of any type) include an additionalAttributes: {} definition that is not documented on the OpenAPI 2.0 Specification, but that allow loose schemas to be compatible with with several services created for OpenAPI/Swagger documented APIs, including code generators and interactive documentation renderers.

Interactive documentation

One way to interact and explore an API is through interactive documentation. SwaggerUI is a resource that allows testing and visualizing the behavior of an OpenAPI described interface.

You can try the instance running on https://kinto.dev.mozaws.net/v1/ from you browser accessing our example on SwaggerHub

Automated client generation

We support clients from a few languages like JavaScript, Python and Java, but if you need a client in a language that is currently not supported or want to have your own personalized interface, you can speedup your development by using Swagger Code Generator, which generates standardized clients for APIs in more than 25 languages.

Using a custom specification

The Kinto OpenAPI description relies on a kinto/swagger.yaml file. You may replace the OpenAPI documentation for your deployment by providing a kinto.swagger_file entry on your configuration file.

OpenAPI extensions

By default all includes on the configuration file will be prompt for a swagger.yaml file on the package root containing an OpenAPI extension for the main specification. You may use it to include additional resources that the plugin provides or override the original definitions. The .yaml files provided are recursively merged in the order they are included (the default description is always used first).

For example, if we want to include a plugin to our spec, we can use a description as follows. The extensions are not required to be valid OpenAPI descriptions, but they can be defined as such. You may also use references that are defined on the base description.

swagger: 2.0
paths:
  '/path/to/my/plugin':
    responses:
      '200':
        description: My plugin default response.
        schema:
          $ref: '#/definitions/MyPluginSchema'
      default:
        description: Default Kinto error.
        schema:
          $ref: '#/definitions/Error'

definitions:
  MyPluginSchema:
    type: object

Important

Extensions that change or include authentication methods may only overwrite the securityDefinitions field. The default security field (used when accessing API endpoints that require authentication) is updated on runtime to match the security definitions.