Versioning APIs

Marcelo Cure

Why do I care?

Why contracts break?

Consumers set expectations

APIs evolve

Non breaking changes

Breaking changes

Breaks consumer :’(

And now?

Version it!

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

How to version my API?

Version as path/query parameter

https://host/api/v1/bands/1/albuns https://host/api/bands/albuns?version=1 ● Explicit

● Cleaner for consumers● Intrusive

Version as a header

Accept: application/json; version=1.0

● Less intrusive● Does not polute URL● No specification for that

Take care of your contracts

● It’s your front door● Care about your design● Discuss contract changes, do it cautiously● Test your contracts

Bad design -> contract break -> versioning

Don’t have a lot of versions

You need to get used...

Contracts break, it’s natural

But not so often

Thanks