Talk about Versioning APIs and contracts

1. Versioning APIs
Marcelo Cure

2. Why do I care?

3. Why contracts break?

4. Consumers set expectations

5. APIs evolve

6. Non breaking changes

7. Breaking changes

8. Breaks consumer :’(

9. And now?

10. Version it!

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

12. How to version my API?

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

15. Version as a header
Accept: application/json; version=1.0
● Less intrusive
● Does not polute URL
● No specification for that

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

18. Bad design -> contract break -> versioning

19. Don’t have a lot of versions

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

21. But not so often

22. Thanks