Versioning APIs

1. Versioning APIs
Marcelo Cure

2. Why do I care?
● Distributed components
● Isolation
● Microservices evolving independently
● Deploy anytime

3. Contracts break

4. Why contracts break?

5. Consumers set expectations

6. APIs evolve

7. We need to change them

8. Non breaking changes

9. Breaking changes

10. Breaks consumer :’(

11. And now?

12. Version it!

13. Communication

14. Be cautious
● Too many versions;
● Complexity;
● Bugs;

15. How to version my API?

16. Version as path/query
parameter
https://host/api/v1/bands/1/albuns
https://host/api/bands/albuns?version=
1 ● Explicit
● Cleaner for consumers
● Harder to identify
● Intrusive

18. Version as a header
Accept: application/json; version=1.0
● Less intrusive
● Does not polute URL
● Easier to identify
● No specification for that
or use a custom
header

20. Take care of your contracts
● It’s your front door
● Care about your design
● Discuss contract changes, do it cautiously
● Postpone decisions
● Test your contracts

21. Bad design -> contract break -> versioning

22. Don’t have a lot of versions

23. Remove deprecated versions

24. You need to get used...
Contracts break, it’s natural

25. But not so often

26. Thanks
Marcelo Cure - Software Engineer at ilegra
marcelo.cure@ilegra.com
Twitter: @__cure
http://marcelo-cure.blogspot.com.br