REST API Versioning

Question

I am currently working on a Java based web application. We recently created some REST endpoints using Spring. The reason for this was because we developed a hybrid mobile application that integrates with our main application through these endpoints.

The problem is that in the future we are not quite sure how to handle updates. If we update our API, for example. if we change the endpoint method method signatures or change the attributes to DTO, which we return as JSON, then we would have a problem if our mobile users are running an outdated version of the mobile application.

What we want to implement is what forces our users to update the application if it is out of date. I have seen many mobile apps that do this. Therefore, we thought about having an API version for our REST API, and then check the mobile application, if the version used is the same as the version launched by our server, and if not, then force the user to update.

We have a problem:

• We have only one version of our server running at any time. So, how are we going to release our releases? What will happen if we release a new version of our API and our mobile application, but the latest version is not yet available in the application store. Then the user will be forced to upgrade, but the updated application is not yet available to them.

• How do we maintain API version number? In a mobile application, we can simply configure this. But it’s nice to have a version number on the server. The reason I say this is because if we make changes to the signature of a method or DTO, etc., and forget to update this version number manually before release? Of course, is there a more automatic way to do this when a unique "API key" is created based on the current API definition? Then we could use this instead of the API version number.

Answer 1

There are a few things you can do.

• Archiving APIs from the start. There are two general approaches I've seen for this with the REST API: placing the URL prefix as /v1 , /v2 , etc. Before all endpoints of a REST resource or using the HTTP Accepts to negotiate versions. There are religious wars in which man is right. This is your API. Do what you think is right.
• Extract business logic from the API endpoint code in your source code. That way you can have endpoints v1 and v2 that reuse common code at a lower level of service level. This is something you do not need to do from the very beginning. You can wait until the v2 API begins to separate things.
• Automatically testing each build against existing versions of the API (and any new version you build, but regression testing is the key point I am doing).
• Forced application updates, or at least tracking the use of the application version, allows you to remove / clear any code that supports legacy versions.

I am working on a similar project, creating a new REST API for a new mobile application. I am sharing the URL space by version, so https: //api.blahblahblah/v1.0/resource .

At the moment, I have my business logic built right into the code that accepts HTTP requests because there is no other benefit to such logic. However, when I need to create a new version, I reorganize the API v1 code to separate everything that is not v1-specific into a more reusable module, which can then be reused.

Depending on how structurally your versions differ, you may need some reduction to keep your API separate. For example, you might need a generic UserEntity object to represent user information from your database, but it requires a UserV1Resource and UserV2Resource object for separate versions with adapters or another design pattern to alert you of the different types that become serialized for JSON or XML.

Having received automated API tests, I can freely perform any of these refactoring, separating them from myself, knowing that the moment I break any backward compatibility, my tests will yell at me.

A good advantage of the API that is still being used by our mobile application is that we only need to worry about compatibility with supported versions of applications. If we can make sure that our end users regularly update their application, we can remove older versions, which will help minimize our technical debt.

Answer 2

It looks like you need to make backward compatible updates for your API.

Since you control the client code calling the API on the mobile side, just copy the application to ignore the new fields that appear in JSON responses. This will make the application much less fragile and allow you to expand your objects as you wish. Use most of HATEOAS and ask your customers to navigate through hyperlinks inside your objects, rather than rigidly linking them to your URL structure.

You should start creating a culture and compatibility testing process with each version of the server so that you can automatically check that your old API clients (which, of course, will live forever on the phones of people who never update their applications) will still work with The update you are planning for your server. In Semantic Versioning, it looks like you have added a minor version update to your API.

If you think that at some point you will need a significantly incompatible API change that will break your old applications, then from the very beginning, create a “compatibility check” with your API clients. At startup, they must check a simple API on the server in order to handshake the base version. If the server says "we just can’t support your old client code anymore", then you will receive an application error message stating that the user pulled the latest version from the application store. But since this is a pretty nasty user experience, it's best to just build reasonable compatibility from the start.