I have finished watching a series of lessons on Designing & Versioning HTTP/REST APIs from well known author Jeffrey Richter who is an author of the best-sellers CLR via C# and Windows API via C++.
I do definitely recommend it to watch (and read the books as well, if you didn't) for those who design Back-End APIs. And especially for those who think that doing API is simple (probably, impressed by several Hello-World prototypes made during the week-ends).
One important thing to note in this article is that it is really important to combine some practice when you do theoretical learning.
This recommendation will work for developers of any level of experience and do not depend on how well-known the author of the book/course is. It is always easy to watch and read something and put a sign "learned" on it. But actual implementation will always put some impediments and this is where things get really interesting.
Now, let's take one piece of advice from the course and let's dive into the topic which is not fully uncovered in the course: on Versioning HTTP APIs part of course. Details I will cover here are really important for the implementation.
REST API everywhere
Most of the public API's go with REST or RESTful approach. Those gRPC, SOAP, GraphQL and other protocols are good for its own purposes, but REST is covering most of the needs:
- It's available for any type of client: old/new browsers, smartphones, low-end computers, Raspberri Pi's and even consoles.
- It uses well-known HTTP language for all the features that API needs, like handling errors, passing auth tokens (headers), transferring all the types of content, bandwidth-control, etc. etc.
- Tons of examples in the internet out there,
- etc.
And, truly saying, for prototypes, local businesses, quick and cheap development it is all you need. All other protocols have been created to solve much more specific needs like scaling, handling low-bandwidth channels, enterprise solutions, etc.
But this simplicity and low entry threshold plays a bad role when it comes to product quality of your Public API. Very few non-senior developers know that Public API's must be backward compatible and sometimes even forward compatible. Tiny portion of developers know how to achieve it.
What's wrong with Public APIs?
API versioning plays crucial role in making your API really desirable for your happy clients. Since the time you have published your API for the first time, things never will be fun for you.
You have to maintain all the base of the clients from version 1.0-pre-alpha till the version 99999...9.0 unless you have been smart enough to publish your Public API Policy of Use. Didn't you? :D
In this policy you can recommend all your clients to update on every release. But it's still just a recommendation.
You can also not guarantee stability of your old versions, but that really depends on your customer relationships.
In any way, you have to label your API version and make sure that clients potentially understand how it works based on documentation and policies that you have provided.
Just follow someone's recommendations in API versioning. What can go wrong?
API version is a label that should tell your clients what to expect. There are various ways of doing so, to mention a few:
- http://api.tactica.xyz/products?api-version=0.1-alpha
- http://api.tactica.xyz/products?api-version=1.0
- http://api.tactica.xyz/products?api-version=2023-01-01
- http://api.tactica.xyz/v0.9-beta/products
- http://api.tactica.xyz/v1.0/products
As you can see, there are many ways to tell your API version to the client. And before you take the first approach in the list, I should tell you that it's not always "up to you". Let's review why you may want to use one or another way.
Basically, there is only 2 approaches that differ a lot:
- Put your API version in the URL
- Put your API version in the parameters
In various sources I've seen approach #1 marked as outdated. However, there are still reasons to keep using it. Let's review those.
Why to pass Version in the URL
- Most of the API Management systems do use "API version in the URI" as a default approach, such as Axway, MuleSoft Anypoint, Google Apigee, Boomi, AWS API portal, Nginx API Management.
- Services co-located behind a DNS endpoint MUST use the same versioning mechanism, so if you already have something (maybe legacy) versioned this way, you better stick with it.
Why to pass Version as a parameter:
- We can guarantee the stability of their REST API's URL paths, even through future versions of the API.
- You can always return a DEFAULT resource without a version even specified. etc.
- Easily change from -preview or -beta to the released and thus, make your development a bit more agile and iterative.
- Gives MORE transparency to the clients -> more information on the date of release
- Split out API BEHAVIOUR from RESOURCE.
- Support Group versioning feature that allows developers to look up a single version number and use it across multiple endpoints. Group version numbers are well known, and services SHOULD reject any unrecognized values.
Phew. Quite a few notes, ha?
Fun thing is that nothing of that is actually mentioned in the course. That's why I wanted to bring this example of the need for questions, which appear right after you start practicing.
More to consider for Public API
Approach to API Versioning should not be afterthought. Each time you want to change a mandatory parameter, or payload formats, replace some old error codes or change a behavior...consider adding new API methods and publishing new versions.
It would be even better if you embed version numbers in the data structure. You may not need that in the beginning, but you will thank yourself when you want to scale (event-driven architecture, etc.).
Conclusion
Following those rules will make your Public API clients happier and your life a bit easier (but a lot, still).
As you may notice, in general, there are many "up to you's" in the API versioning, starting from policies and right to the technical details. But that is not usually part of any book or a course and this is something you have to solve on your own.
Next time, before finishing your training course, take your time to practice a little bit. I'm sure you will find many places to raise a hand and discuss with your experienced colleagues or a community.
Top comments (0)