> For the complete documentation index, see [llms.txt](https://jen-hsuan-hsieh.gitbook.io/asp-net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jen-hsuan-hsieh.gitbook.io/asp-net/chapter3rest-api-design-development-and-management/33designing-rest-api/337versioning-the-api.md).

# 3.3.7.Versioning the API

* Versioning
  * Creation and management of multiple release of a software
    * Not the same as version control: 開發者可以任意挑選不同版本的API

      ![](/files/-M4M0XF3yxaMCEROUMrB)
* Version format
  * 1.Use the date of release 
    * e.g., version = "10/1/2015", twilio
  * 2.major.minor 
    * e.g., version = "12.61", Facebook
  * 3.Single digit i.e., No minor version 
    * e.g., version = "12", Uber
* Version information
  * 1.HTTP header
    * e.g., x-myapi-version: 1.2
  * 2.Query parameter
    * e.g., /post?version=1.2, facebook
  * 3.URL
    * e.g., /v1/products, Uber
* Hybrid approach    
  * [Stripe](https://stripe.com/)
    * Major change: <http://api.stripe.com/v1/charges>
    * Minor change: HTTP Header: "2016-07-06"
* API versioning mandatory
  * "v" followed by
  * Major version only
  * In the URL
* API Change strategy
  * quarterly release cycle
    * 開發者至少都有兩個版本可以使用

      ![](/files/-M4M0XF59NjebozNum_P)
  * Multiple version support key points
    * 1.Support at least 1 previous version for a period of time
      * e.g., 3 months
    * 2.Mark the previous version as deprecated
      * For new apps developers can access only the latest version
    * 3.Publish a roll out plan in advance
    * 4.Manage change log that shows the reason for new version