Presentation about versioning rest apis's and how to do it

1. Versioning
Gabriel Passos
Jt Dev

2. The Problem?
● Contract:
○ What your client consume
● Contract Break
○ Change or remove data;

3. Solution?
● Versioning
○ Creates a new version of API
○ The older version will “live” for
determined time

4. Must take care
● Your API mustn't support too much versions
○ Messy code
○ A lot of branches
○ Bugs
○ Avoid more than 2 versions
● Accumulates contract breaks and release the new version

5. Must take care
● http://localhost:8080/v1/user/v2/address/v4/street
● http://localhost:8080/v1/user/v3/address/v3/street
○ Do not create a waterfall

6. How to versionate?
● URI Versioning – version the URI space using version indicators
● Versioning URI Parameters – version parameters
● Media Type Versioning – version the Representation of the Resource

7. URI Versioning
● Changes creates new uri (PathParam)
-> http: //localhost:8080/version1/users
-> http: //localhost:8080/version1/account
-----------------------------------------------
-> http://localhost:8080/version2/users
-> http: //localhost:8080/version2/account

8. URI Versioning
● Pros
○ Clear (Dev Friendly)
-> http: //localhost:8080/version1/users
-> http://localhost:8080/version2/users

9. Versioning URI Parameters
● Uses the new version as query parameter
-> http: //localhost:8080/users?version=1
-> http: //localhost:8080/account?version=1
-----------------------------------------------------------
-> http://localhost:8080/users?version=2
-> http: //localhost:8080/account?version=2

10. Versioning URI Parameters
● Pros
○ Don’t break hyperlinks used
○ Don’t change resource name or location
● Cons
○ Frameworks don’t support

11. Media Type Versioning
● Use the header
Accept: application/vnd.myapi.version + media_type

12. Media Type Versioning
● Pros
○ Uses vendor, that is already done
● Cons
○ Hides the versioning, that could make the work harder

13. Semantic Versioning
● 2.0.0
○ Major:
■ Contract Breaks
○ Minor:
■ Adding functionalities, backwards-compatibles
○ Patch:
■ Backwards-compatible bug fixes.

14. Polemic
● Counter Argument
○ “If you need to change the api you should rewrite it ”

15. References
● http://www.baeldung.com/rest-versioning
● http://blog.restcase.com/restful-api-versioning-insights/
● https://semver.org/
● http://marcelo-cure.blogspot.com.br/2016/05/versioning-apis.html
● http://h17007.www1.hpe.com/docs/enterprise/servers/oneviewhelp/oneviewRESTAPI/content/
s_rest-verison-overview-sdk-fusion.html

16. Support Material
● https://blogcoreengineering.wordpress.com/2018/01/09/versioning-rest-apis/