HOW TO (NOT) VERSION YOUR API

5-in-5 @RESTfest

Michael Pratt

@urthen

http://urthen.github.io/2013/05/09/ways-to-version-your-api/

Why version your API?

One overwhelming reason:

Prevent breaking client applications

Clients have control over their own upgrades

Versions can be deprecated on a schedule

How to version your API

Build a new one.
Add version to URI Template
Add version to Query Parameters
User Configuration
Passing a Custom Header
Accept Header Parameter

How to NOT version your API

Entities have few states of being (2xx, 3xx, 410, 404)
Entities must exist or not
Use future-proofed URI templates
Version representations, not your API
Follow well-defined verbs

GET: gets data from resource
POST: wildcard - accepts entities, not idempotent
PUT: creates or replaces entity at location
PATCH*: edit entity in place
DELETE: deletes entity at location

Good:

http://www.example.com/api/bars/1

or, generically:

http://hostname/api_name/resource_name/id(/subresources?)

Bad:

http://www.example.com/api/bars.json
http://www.example.com/api/addNewBar
http://www.example.com/api/getBar?id=1

Why this is important

(and also doesn't really matter)

URLs should be static and long-lasting
URLs should not indicate resource types or actions
Breaking client applications makes them sad
If you're using hypermedia, it matters a lot less

Unless people don't use them!

Takeaways

Always think of your versioning
Try not to duplicate code when you do
Use (and write) libraries for versioning
Promote standards!

How to not version your API 5 in 5

By Michael Pratt

How to not version your API 5 in 5

2,276

Michael Pratt