3.3.7.Versioning the API

• Versioning

  • Creation and management of multiple release of a software

    • Not the same as version control: 開發者可以任意挑選不同版本的API

      

• 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

    • 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

    • 開發者至少都有兩個版本可以使用

      

  • 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