<p>Many APIs include a version number in the url of the service. Some examples:</p>

<ul>
<li><a href="https://api.twitter.com/1.1/statuses/home_timeline.json" rel="noreferrer">https://api.twitter.com/1.1/statuses/home_timeline.json</a></li>
<li><a href="https://graph.facebook.com/v2.2/me/adaccounts" rel="noreferrer">https://graph.facebook.com/v2.2/me/adaccounts</a></li>
<li><a href="https://vision.googleapis.com/v1/images:annotate?key=YOUR_API_KEY" rel="noreferrer">https://vision.googleapis.com/v1/images:annotate?key=YOUR_API_KEY</a></li>
<li><a href="https://maps.googleapis.com/maps/api/js?v=3.29" rel="noreferrer">https://maps.googleapis.com/maps/api/js?v=3.29</a></li>
<li><a href="https://westeurope.api.cognitive.microsoft.com/vision/v1.0/analyze" rel="noreferrer">https://westeurope.api.cognitive.microsoft.com/vision/v1.0/analyze</a></li>
<li><a href="https://www.europeana.eu/api/v2/opensearch.rss?searchTerms=Rembrandt" rel="noreferrer">https://www.europeana.eu/api/v2/opensearch.rss?searchTerms=Rembrandt</a></li>
</ul>

<p>However many people on the Internet argue that this is incorrect because it violates REST/HTTP specifications; <a href="https://stackoverflow.com/a/398564/741249">"embedding of API version into the URI would disrupt the concept of hypermedia as the engine of application state"</a>. It’s more appropriate to <a href="http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http" rel="noreferrer">use the Accept header to request a particular version</a>. For the latter people suggest to use a Vendor MIME type, for example something like <code>Accept: application/vnd.mycompany-api-v3+json</code></p>

<p>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).</p>

<p><em>Side note:</em> 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).</p>

CC BY-SA 3.0
2018-03-03T17:01:32.907Z
2018-03-03T17:01:32.907Z
THelper
<p>I was looking for the current version of the github API, but it seems to be omitted.</p>

<p><a href="https://api.github.com/" rel="noreferrer">https://api.github.com/</a></p>

<p>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.</p>

<api>
Is it a common practice to include the version of an API into the rest interface itself?
030
# Is it a common practice to include the version of an API into the rest interface itself?

(Asked by: username_0 on 2018-03-03)

I was looking for the current version of the github API, but it seems to be omitted.

<https://api.github.com/>

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.

**Tags:** api


---

## 1 answers

### Answer by username_1 on 2018-03-03. Score: 9 | Accepted 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"](https://stackoverflow.com/a/398564/741249). It’s more appropriate to [use the Accept header to request a particular version](http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http). 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).


---

