Design Patterns – Planning REST Endpoints for Future Changes

designdesign-patternsrestservicesweb services

Trying to design an API for external applications with foresight for change isn't easy, but a little thought up front can make life easier later on. I'm trying to establish a scheme that will support future changes while remaining backward compatible by leaving prior version handlers in place.

The primary concern on this article is to what pattern should be followed for all defined endpoints for a given product/company.

Base Scheme

Given a base URL template of https://rest.product.com/ I have devised that all services reside under /api along with /auth and other non-rest based endpoints such as /doc. Therefore I can establish the base endpoints as follows:

https://rest.product.com/api/...
https://rest.product.com/auth/login
https://rest.product.com/auth/logout
https://rest.product.com/doc/...

Service Endpoints

Now for the endpoints themselves. Concern about POST,GET,DELETE is not the primary objective of this article and is the concern on those actions themselves.

Endpoints can be broken down into namespaces and actions. Each action must also present itself in a way to support fundamental changes in return type or required parameters.

Taking a hypothetical chat service where registered users can send messages we may have the following endpoints:

https://rest.product.com/api/messages/list/{user}
https://rest.product.com/api/messages/send

Now to add version support for future API changes which may be breaking. We could either add the version signature after /api/ or after /messages/. Given the send endpoint we could then have the following for v1.

https://rest.product.com/api/v1/messages/send
https://rest.product.com/api/messages/v1/send

So my first question is, what is a recommended place for the version identifier?

Managing Controller Code

So now we have established we need to support prior versions we need to thus somehow handle code for each of the new versions which may deprecate over time. Assuming we are writing endpoints in Java we could manage this through packages.

package com.product.messages.v1;
public interface MessageController {
    void send();
    Message[] list();
}

This has the advantage that all code has been separated through namespaces where any breaking change would mean that a new copy of the service endpoints. The detriment of this is that all code needs to be copied and bug fixes wished to be applied to new and prior versions needs to be applied/tested for each copy.

Another approach is to create handlers for each endpoint.

package com.product.messages;
public class MessageServiceImpl {
    public void send(String version) {
        getMessageSender(version).send();
    }
    // Assume we have a List of senders in order of newest to oldest.
    private MessageSender getMessageSender(String version) {
        for (MessageSender s : senders) {
            if (s.supportsVersion(version)) {
                return s;
            }
        }
    }
}

This now isolates versioning to each endpoint itself and makes bug fixes back port compatible by in most cases only needing to be applied once, but it does mean that we need to do a fair bit more work to each individual endpoint to support this.

So there's my second question "What's the best way to design REST service code to support prior versions."

Best Answer

So there's my second question "What's the best way to design REST service code to support prior versions."

A very carefully designed, and orthogonal API will probably never need to be changed in backward incompatible ways, so really the best way is not to have future versions.

Of course, you probably won't really get that the first try; So:

Version your API, just as you are planning (and it's the API that is versioned, not individual methods within), and make lots of noise about it. Make sure that your partners know that the API can change, and that their applications should check to see if they are using the latest version; and advise users to upgrade when a newer one is available. Supporting two old versions is tough, supporting five is untenable.
Resist the urge to update the API version with every "release". The new features can usually be rolled into the current version without breaking existing clients; they're new features. The last thing you want is for clients to ignore the version number, since it's mostly backwards compatible anyway. Only update the API version when you absolutely cannot move forward without breaking the existing API.
When the time comes to create a new version, the very first client should be the backwards-compatible implementation of the previous version. The "maintenance API" should itself be implemented on the current API. This way you aren't on the hook for mantaining several full implementations; only the current version, and several "shells" for the old versions. Running a regression test for the now deprecated API against the backwards comaptible client is a good way to test out both the new API and the compatibility layer.

Related Solutions

Microservices – Public API Facade Implementation

There are two authorization models that are common: trusted subsystems and delegation.
- Trusted subsystems is an architecture in which the user creation & message creation services trust the API application to perform the user authentication & authorization. In this model, the API application is trusted (via network ACLs, tokens, x509 certificates, etc.) and can interact with both services in an unrestricted capacity.
- Delegation is an alternative architecture where the API calls the microservice on behalf of the user; in such a model, both the API & the microservices would handle authorization, with the microservices validating both the identity of the API application and the claims of the user making the original request. The API validates that the user is authenticated & authorized to make the request, while the "message" microservice validates that both the application is trusted and the user is authorized to create messages.
There are tradeoffs between these two approaches; trusted subsystems is an easier architecture easier to implement, but delegation enables more advanced security features. For your application, it is likely much easier to follow the trusted subsystem strategy, so I would strongly consider building authn/authz at the API "facade" (maybe gateway is a better word here?).
EDIT: The answer depends heavily on what the message service is doing, and what data is required for it to carry out its duties. If the message service is just routing messages in realtime to websockets, the requirements may be different than if the messages are persisted to a database. In general, though, it's possible that the service interacts with user IDs without being directly coupled to the user service (e.g. storing the messages in a table as sender_id, recipient_id, and message).

Check out this post for more on delegation and traversing layers.

Design Pattern for Implementing REST Services on Mobile

Treat the REST API as any other data source, and create an abstraction (e.g. AppointmentRepository, etc.) that your controllers use. My examples are in Java, but I think you'll get the idea.

public interface AppointmentRepository {
    Appointment findById(String id) throws RepositoryAccessException;
    void create(Appointment appointment) throws RepositoryAccessException;
    void update(Appointment appointment) throws RepositoryAccessException;
    void delete(Appointment appointment) throws RepositoryAccessException;
}

public class RestAppointmentRepository {
    @Override
    public Appointment findById(String id) throws RepositoryAccessException {
        // make the API call
        // translate the JSON to an Appointment object
        return appointment;
    }
    // etc
}

Using an abstraction in this way decouples your controller from the concrete source of data, so the two can change without affecting each other. Consider if in the future the REST API changes its representation of an appointment, which means your mapping code needs to change. When that mapping code is hidden behind an abstraction, there's no need to make any changes to the controller to handle the REST API change.

This approach also allows you to more easily unit-test your controller without having to worry about the REST API returning data to support your unit tests. In addition to the happy-path test, you should be testing that your controller reacts appropriately when the REST API is unavailable, i.e. when the repository method throws an exception. Take the repository interface as a dependency of the controller, and mock it in your unit test so that you can define its behavior easily.

public AppointmentController extends ViewController {
    private final AppointmentRepository appointmentRepository;

    public AppointmentController(final AppointmentRepository appointmentRepository) {
        Preconditions.checkNotNull(appointmentRepository);
        this.appointmentRepository = appointmentRepository;
    }
}
...
// unit test
AppointmentController appointmentController = new AppointmentController(mockAppointmentRepository);