Member-only story
3 Better Ways to Handle REST API Versioning
Techniques on updating versions as infrequently and slowly as possible
In my previous article on Designing REST APIs, I talked about using a simple versioning scheme for APIs. Over a period of time, I’ve realized that no matter how simple you keep your versioning scheme, it’s always a pain to move consumers from one version to another.
If you look around, the internet is flooded with opinions about API versioning schemes. When you use versioning, you need to think about maintaining backward compatibility for a certain time, until all consumers are moved to the new version. It takes a lot of energy, communications, and planning to make these things happen.
In this article, I’m going to discuss some methods you can use to help you avoid having to update the API versions.
New Attributes in Schema
It is expected that over the period of time, you will need to add more attributes to your schema. Adding new attributes does not introduce breaking changes in most cases. So, if you are just adding new attributes, you should not update the versions.
For example, if you have an API as described:
/v1/products{ "name" : "abc",
"id" : 1,
"price" : 30,
"description" : "All good stuff about abc"
}
And you would like to add a new attribute called stock, then you can introduce this without updating the version:
/v1/products{ "name" : "abc",
"id" : 1,
"price" : 30,
"description" : "All good stuff about abc",
"stock" : 10
}
This technique is indeed very popular and I am pretty sure many of you might be using it already.
PATCH over PUT
When you want to provide update capabilities, it is recommended to use PATCH rather than PUT . Just in case you are unaware, PUT is used to update the entire resource while PATCH is used to update partial resources.
If you are making schema changes and if you don’t allow PATCH operation then consumers need to update their code. On the other hand, if you use PATCH operation then consumers don’t need…
