Rest API Documentation - Gier API... · Rest API Documentation {{}, {}],}
How to deal with REST API Evolution
Transcript of How to deal with REST API Evolution
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