An API is like a contract between a client and server. If either interface changes, typically on the server side, the contract fails. However, APIs need to evolve, as new features get added and old ones get deprecated.

Hence, the API versioning is a key design decision taken early on in an API lifecycle. There are several popular API versioning implementations:

• URI versioning: Prefixing the URI with the version number, such as http://example.com/v3/superheroes/3 . This is a popular method but violates the principle that each resource has a unique URI across versions.
• Query string versioning: Appending the URI with a query string specifying the version, such as http://example.com/superheroes/3?version=3 . Technically, the URI is the same across versions, but such responses are not cached in older web proxies, thereby degrading performance.
• Custom header versioning: Including a custom header in your requests; take the following for instance:

    GET /superheroes/3 HTTP/1.1 
    Host: example.com 
    Accept: application/json 
    api-version: 3 

While this might be closer to REST principles and cleaner, it can be harder to test in some web clients, like browsers. Custom Headers are outside specs and might cause latent issues that can be hard to debug.

• Media type versioning: Use the Accept header to specify a custom media type that explicitly mentions the version; consider this for instance:

    GET /superheroes/3 HTTP/1.1 
    Host: example.com 
    Accept: application/vnd.superhero-api.v3+json 

While this may also have testing issues, like custom headers, it honors the standard. This might be the purest REST versioning model.

There are other design decisions to make too, such as which versioning scheme should be followed? Should it be a simple incrementing integer (as in the preceding examples), a semantic version (like Facebook), or the release date (like Twilio)? It is quite similar to a product versioning exercise.

Backward compatibility is also an important API lifecycle decision. How many older versions to keep? What determines a minor or major version change? How to deprecate older versions?

It is best to have a clearly communicated policy that is followed consistently.