Versioning APIs

Marcelo Cure

Why do I care?

● Distributed components● Isolation● Microservices evolving independently● Deploy anytime

Contracts break

Why contracts break?

Consumers set expectations

APIs evolve

We need to change them

Non breaking changes

Breaking changes

Breaks consumer :’(

And now?

Version it!

Communication

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● Harder to identify● Intrusive

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

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

Bad design -> contract break -> versioning

Don’t have a lot of versions

Remove deprecated versions

You need to get used...

Contracts break, it’s natural

But not so often

Thanks

Marcelo Cure - Software Engineer at ilegra

marcelo.cure@ilegra.com

Twitter: @__cure

http://marcelo-cure.blogspot.com.br