API Versioning

[Bargs]

As we begin to add API endpoints to Kibana (#5199), we should think about how we want to handle versioning. The big questions are 1. Where does the version info go in the request and 2. How do we support multiple versions on the backend?

Some popular options:

1. Put the version in the URL
2. Put the version in a custom header
3. Put the version in the accept header
4. ???

I personally prefer the accept header because that's the sort of thing content type negotiation is for, custom headers are hacky and URLs should specify a resource not an API version.

[rashidkpc]

I can think of no good reason to support multiple versions on the backend, nor really any reason to version the API at all. We version stored objects because we may need to upgrade them, but for APIs we can simply follow the already understood semver rules of Kibana

[kimjoar]

Versioning APIs is always a major pain — everything is so much easier if we can avoid it.

[pickypg]

To narrow the scope of this issue, it is only about future REST APIs.

The use case for this is so that outside code can depend on the API format for the REST endpoint(s). In particular, by creating an API version that is separate from the application version, users can depend on the endpoint more simply. This is particularly relevant for any ingestion endpoints, where tools can be written and deployed without the ability to easily update them. They can talk to a version of the ingest API, even as newer versions of it get released.

For example, imagine Elasticsearch removes _type support. Therefore all old mappings are thus broken (if attempted to be sent) and any attempt to create a new one using an existing API is most likely broken as well. Any tool that's used to ingesting data into Elasticsearch, in such a world, is therefore now incompatible. The indexing APIs require the type to be specified in one place or another.

PUT /{index}/{type}/{id}
{}
POST /{index}/{type}
{}
POST /{?index}/{?type}/_bulk
{"index":{"index":"", "type":""}
{}

There's no avoiding such a breaking change. Versioning the API wouldn't save you (they either want to send _type or they don't, but it's not right to ignore _type at such a level) and every tool is now broken.

In a less scary example, imagine that Kibana has an API to create new Index Patterns that uses _type. Now, imagine the Elasticsearch breaking change above. Kibana can update its own API to simply ignore the type while introducing a new API that drops type; Kibana is in a position to drop type, unlike Elasticsearch.

The strictness therefore lands at our feet in such a world. We can make breaking changes to such APIs, but ideally we can add them in BWC ways, or by adding a new version that lives beside the old [deprecated] version. In the worst case, we can still make a scary Breaking Change that simply prevents them from working. At that point, when the API doesn't exist, it's up for the application to react (e.g., degrade to the older version or simply fail) rather than calling it and hoping for the best.