Download - 20160908 #NoAPIVersioning
![Page 1: 20160908 #NoAPIVersioning](https://reader037.vdocumente.com/reader037/viewer/2022100800/58ed3a7b1a28ab367e8b45af/html5/thumbnails/1.jpg)
#NoAPIVersioningMobile Tea #11 Stephen Vance
September 8, 2016
![Page 2: 20160908 #NoAPIVersioning](https://reader037.vdocumente.com/reader037/viewer/2022100800/58ed3a7b1a28ab367e8b45af/html5/thumbnails/2.jpg)
Easy API Changes
Add an endpoint
Add an optional element or parameter
Remove something no one uses
đ
2
![Page 3: 20160908 #NoAPIVersioning](https://reader037.vdocumente.com/reader037/viewer/2022100800/58ed3a7b1a28ab367e8b45af/html5/thumbnails/3.jpg)
Breaking API Changes
Removing something people use
Change a data type
Add a required parameter or element
Change the response structure
đ
3
![Page 4: 20160908 #NoAPIVersioning](https://reader037.vdocumente.com/reader037/viewer/2022100800/58ed3a7b1a28ab367e8b45af/html5/thumbnails/4.jpg)
What Shouldnât You Do?Donât change! Let it break!
Version your endpoint namespace example.com/api/v2345/users
Version your API domain v456.example.com/api/users
Version your content type Content-type: application/vnd.example.user-v17+json
Version your content { version: 6543, ⌠}
4
![Page 5: 20160908 #NoAPIVersioning](https://reader037.vdocumente.com/reader037/viewer/2022100800/58ed3a7b1a28ab367e8b45af/html5/thumbnails/5.jpg)
What Should You Do?⢠Code for Compatibility
⢠Useful in short term
⢠Increasing complexity and cost over time
⢠Hypermedia (HAL, JSON-LD, Collection+JSON, âŚ)
⢠Livinâ the dream
⢠Conceptual complexity
⢠Limited practical support
⢠Migration
⢠Managed compatibility with an expiration
5
![Page 6: 20160908 #NoAPIVersioning](https://reader037.vdocumente.com/reader037/viewer/2022100800/58ed3a7b1a28ab367e8b45af/html5/thumbnails/6.jpg)
Code for Compatibility
Rename â Two options with sync or translation
Mandatory parameter â Optional parameter with default value
Deletion â Ignored optional
Type change â Type flexibility
6
![Page 7: 20160908 #NoAPIVersioning](https://reader037.vdocumente.com/reader037/viewer/2022100800/58ed3a7b1a28ab367e8b45af/html5/thumbnails/7.jpg)
Hypermedia⢠Hypermedia Controls tell you what to do next for each
workflow option
⢠You still need to program the semantics of the options if theyâre not strictly user injected
⢠Hypermedia Forms tell you the data content for each request
⢠You still need to program the semantics if itâs more complex than CRUD
⢠Hypermedia Templates tell you how to assemble the data into the request
7
![Page 8: 20160908 #NoAPIVersioning](https://reader037.vdocumente.com/reader037/viewer/2022100800/58ed3a7b1a28ab367e8b45af/html5/thumbnails/8.jpg)
Migrations⢠Automatically generate compatibility changes and
rollback
⢠Manage application and lifecycle of compatibility
⢠Integrates with deployment systems to eliminate downtime
⢠Also applies to database schema
⢠Requires ability to sunset compatibility
⢠Coming to an environment near you. Watch this space!
8
![Page 9: 20160908 #NoAPIVersioning](https://reader037.vdocumente.com/reader037/viewer/2022100800/58ed3a7b1a28ab367e8b45af/html5/thumbnails/9.jpg)
Resources
⢠Sebastian Lambla, âVersions are Evil: How to Do Without In Your APIâ
⢠Richardson & Amundsen, âRESTful Web APIs,â OâReilly, 2013.
9
![Page 10: 20160908 #NoAPIVersioning](https://reader037.vdocumente.com/reader037/viewer/2022100800/58ed3a7b1a28ab367e8b45af/html5/thumbnails/10.jpg)
Contact Me
Stephen Vance
http://www.vance.com
@StephenRVance
srvance on GitHub and LinkedIn
10