This document discusses different approaches to versioning APIs, including URI versioning, versioning URI parameters, and media type versioning. It recommends URI versioning, as it provides a clear, developer-friendly way to differentiate versions. It also suggests following semantic versioning principles of using major, minor, and patch versions to indicate breaking changes, additions of functionality, and backwards compatible bug fixes. The key is to avoid supporting too many versions to prevent code from becoming messy and bug-prone.

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/