A sensible (RESTful) API change management guide @nuwanbando Mar, 2019

Types of API versioning - URI based (globally at the API level, at resource level, in query params) http://api.example.com/v1.2.3/person and/or http://api.example.com/v2.1.1/company a. Resource identifier is intermingled with the API implementation detail b. API caching, bookmarking, crawling at the client becomes difficult c. Very coarse-grained and limits independent evolution of subcomponents d. End to end testing nightmare - Mime-based resource versioning (i.e: github api versioning) - https://api.github.com/users/octocat/orgs Accept: application/vnd.github.v3+json - Clever trick to keep the URI intact, so the identifier is constant across - Same drawbacks as URI based versioning on point C and D above

Explicit SemVer is a bad idea for an evolving RESTful API - Semantic versioning make sense for software modules but not the best option for independently evolving distributed systems - A minor change will enforce a new version which will tightly couple the client and server for a given version - Note on the “explicit” fact - Versions can and should be used implicitly in API documentation, in response headers, release notes but not explicitly at API

What is the right way ? (There is no “one” right way to do versioning) - Have few major versions (breaking changes) - Make changes backward compatible as possible - Set expectations for the clients: thinking about forward compatibility - Tell clients to expect and handle (as gracefully as they can) responses like 410 Gone, 405 Method Not Allowed, and 415 Unsupported Media Type. - Keep compatible changes out of identifiers - No http://api.example.com/v1.2.3/person - Make minor and patch versions discoverable using other means - API documentation, release notes, response headers etc.

A sensible API change management guide - Identify what and what not to version - What to version: - The server implementation (code/app) - The client implementation (code/app) - Message format transferred between the client and the server (content negotiation for a specific message format) - API description file (openAPI document) - What not to version: - The API: http://api.mydomain.com/v1 - The resource: v1::customer - The relationships between resources: customer::v1 cannot have a relationship with business::v2

A sensible API change management guide - Having a set of rules for extending / evolving the API - Do not take things away from the API - Don’t remove methods/resources/params etc - Do not change processing rules - Don’t change how you process the request content - Do not make optional things required - Not making optional parameters required in forward changes - Anything you are adding to the existing has to be optional - Above rules will guarantee backward compatibility for the API - These rules follow Postel’s law - This also means communicating to the clients to be liberal (forward-compatibility)

A sensible API change management guide - If you need to introduce breaking change like - Change to the URI including URI params - Resource metadata (headers etc.) - Resource data (fields, content body and semantics) - Resource actions (GET/PUT etc.) - Relationships to other resources

A sensible API change management guide - What you must do ? - Introduce a new variant - Ie: current implementation of /helloWorld?name=John has optional name which needs to be required - Don’t change /helloWorld but introduce /helloWorldFrom?name=john - If change introduces a new message format - use content negotiation

A sensible API change management guide - Maintenance - Being mindful about introducing breaking changes - Breaking changes means introducing a new variance which is not ideal - Start using @deprecated in API documentation and communicate to the clients about the evolving nature of the API - Have a deprecation plan with an API Management solution - Use API analytics to find out the usages of older variances - once no usage, plan to sunset - Still use a 303 - redirect to the new variance as a best practice

References & inspired by - https://semver.org/ - https://www.mnot.net/blog/2012/12/04/api-evolution.html - https://twitter.com/fielding/status/376835835670167552?s=20