Learn With Practice: API Versioning Snags

I have finished watching a series of lessons on Designing and 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++.

For those who design back-end APIs, I do definitely recommend watching it (and reading the books as well, if you haven't), especially those who think that doing an API is simple (probably, impressed by several "Hello, World!" prototypes made during the weekends).

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 does 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 part that covers the topic of versioning HTTP APIs.

REST API Everywhere

Most of the public APIs go with REST or RESTful approaches. Those gRPC, SOAP, GraphQL and other protocols are good for their 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, Raspberry Pis, and even consoles.
• It uses well-known HTTP language for all the features that an API needs, like handling errors, passing auth tokens (headers), transferring all types of content, bandwidth control, etc.
• Many examples are available on the internet 

And, truly saying, for prototypes and local businesses, quick and cheap development 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 play a bad role when it comes to the product quality of your public API. Very few non-senior developers know that public APIs must be backward compatible and sometimes even forward compatible. A tiny portion of developers knows how to achieve it. 

What’s Wrong With Public APIs?

API versioning plays a crucial role in making your API really desirable for your happy clients. Since you published your API for the first time, things never have been fun for you.

You have to maintain all the bases of the clients from version 1.0-pre-alpha until version 99999...9.0, unless you have been smart enough to publish your public API policy of use. Didn't you? :)

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 the 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 the documentation and policies that you have provided.

Just Follow Someone’s Recommendations in API Versioning: What Can Go Wrong?

An 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 are only 2 approaches that differ significantly:

1. Put your API version in the URL.
2. 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 Pass a Version in the URL

• Most of the API Management systems do use "API version in the URL" as a default approach, such as Axway, MuleSoft Anypoint, Google Apigee, Boomi, AWS API portal, and 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 Pass a 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 BEHAVIOR from RESOURCE.
• Support the 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?

The 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

The approach to API versioning should not be an afterthought. Each time you want to change a mandatory parameter, the payload format, 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 is 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.