Answers: <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>
  
Answers: CC BY-SA 3.0
Answers: 2018-03-03T17:01:32.907Z
Answers: 2018-03-03T17:01:32.907Z
Answers: THelper
Body: <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>
  
Tags: <api>
Title: Is it a common practice to include the version of an API into the rest interface itself?
UserDisplayName: 030
ThreadText: # 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).
  
  
  ---
  
  