I was looking for the current version of the github API, but it seems to be omitted.
I am personally considering to add a new field to my own API, but I wonder whether that is a common practice or should be done differently.
Add a comment
|
1 Answer
Many APIs include a version number in the url of the service. Some examples:
- https://api.twitter.com/1.1/statuses/home_timeline.json
- https://graph.facebook.com/v2.2/me/adaccounts
- https://vision.googleapis.com/v1/images:annotate?key=YOUR_API_KEY
- https://maps.googleapis.com/maps/api/js?v=3.29
- https://westeurope.api.cognitive.microsoft.com/vision/v1.0/analyze
- https://www.europeana.eu/api/v2/opensearch.rss?searchTerms=Rembrandt
However many people on the Internet argue that this is incorrect because it violates REST/HTTP specifications; "embedding of API version into the URI would disrupt the concept of hypermedia as the engine of application state". It’s more appropriate to use the Accept header to request a particular version. For the latter people suggest to use a Vendor MIME type, for example something like Accept: application/vnd.mycompany-api-v3+json
Nevertheless, the reason why many API designers do include an API version in the url is because it's easy to implement and debug (clearly visible which version you are using).
Side note: in our organization we recently decided to support both a versionless endpoint that always point to the latest stable version of our APIs, as well as an endpoint with a version specification. This allows users to choose if they want to commit to our latest API (which may require making changes when a newer version is released), or to connect to a fixed API version (which may become deprecated over time).
