How to deal with REST API Evolutionwhen offering a service

Nothing Endures but ChangeWith continuous deployment, your API changes all the time.

Clients must keep working with each future API version.

DesignDevelopTestRelease

V 1.0 V 1.1 V 1.2 V 1.3

Internal API Partner API Public APIYou control/deploy your

client(s)

All clients are maintained and deployed by your company.Breaking changes are no issue.

You can coordinate deployment of the clients

You have external clients but you know who they are.Breaking changes are allowed but require coordination and slow down deployment time.

No control whatsoever over your external clients

Anyone can use our API.Can never afford to introduce breaking changes.

Who is Using Your API?

What Can Change?

Syntax

Protocol / domainResource pathQuery params

URI

Request / Response PayloadField added/removed/renamed

Possible values of a field expanded/reduced

Field order

Others

Field validation (type, optional/mandatory, etc.)

Status codes added/removedHeaders

HTTP method (e.g. PUT POST)

very unlikely unlikely not unlikely likely

very likely

Avoid using custom headers

What Can Change?

Semantics

PUT /garage/cars {"name": "Tesla", "id": "4"} Creates a new car with id “4” Creates a new car with generated id “435” (ignores your id)

GET /garage/cars?search=Tesla

Searches for all cars named “Tesla” Does a fuzzy search for “Tesla” (name, type, case-insensitive)

Functional behavior Rate limit

Authentication modelResponse times...

Non-functional behavior

V 1.0V

1.1

V 1.0V

1.1

Change, but Never Break!… and you won't need versioning if you (the service)• never require additional query or header

parameters• never require additional fields on requests• never remove fields from responses• never change your status codes• ignore query parameters that you do not recognize• ignore fields that you do not recognize

Postel's Law: Be conservative in what you do, be liberal in what you accept from others.

Ask one thing from your clients…. “Ignore any extra data (fields, headers, ..) while communicating with the server” *

* And don't rely on field order. Who does that anyway!?

If You See No Other Way, Version!A Version Bump• Must still guarantee backwards compatibility (keep old endpoints)• No easy upgrade path for clients (introduces new endpoints).• For the API owner/implementer's convenience: don't abuse it!

How? Content type / Accept header • Vendor mime types

e.g. GitHub, application/vnd.github[.version]

Avoid versioning by adding a feature toggleOnly for small changes! – through an optional query param• e.g., turn on additional validation ?validateUniqueName=true (default: no validation)• e.g., support an alternative image format (was only jpg) ?imageFormat=png (default:

jpg)• NOT ?apiVersion=5

https://tools.ietf.org/html/rfc4288#section-3.2

Keep all your endpoints forever

(very hard).

Ensure usage is low before shutting down endpoints.If you know the customers that are still using it (authenticated), notify them.

Dealing with Deprecation

Don't deprecate

Document Monitor your endpointsCreate a migration/upgrade

guide.Communicate, set dates!

OK

Unintended Breaking Changes

Prevent unintended changesIndependent RESTful unit/integration tests• Put in a separate project that isn't edited/refactored with the main project• Don't reuse the formatters/parsers from the main or common project

Consumer Driven Contracts (ideal for partner APIs)• Your customers write an independent test suite for the part of your API they use• You run these tests as part of your build

Changing a seemingly insignificant implementation detail may trickle all the way down to the APIe.g., renaming a variable in code, removing an unused field

Conclusion• Your API will change continuously.• You will have to deal with old clients.• Lots of ways to avoid versioning.• Good initial design is important!• You should guard against unintentional breaking

changes.

How to deal with REST API Evolution

We generate your API docs straight from your Java source codeIntegrates with Maven or Gradle and requires no additional annotations

www.miredot.com

Miredot helps you with API evolutionInstant up-to-date docs of each new version

Documentation quality dashboardAPI compatibility check (in private beta)

Thank you!

Questions / ideas / comments?

@bertvanhooff@miredot