API End Points

In recent years, there has been a paradigm shift towards Microservices. Together with Domain Driven Design, it provides a good technique to develop complex enterprise wide business functionality. Of course, there are numerous challenges in both these techniques that require skill and patience (at times) to achieve the end result.

Irrespective of a technique or framework, the most important aspect of any large scale application is its 'modelling'. This includes modelling of API, domain, database, etc. Of particular interest to me is the API design. I have noticed that unless you design public APIs, teams don't give too much importance to this topic. As functionality gets developed across the client - server architecture, APIs are built more like 'raw' Remote Procedure Calls (RPC). Every API is meant to be be invoked from 'your own' client at a 'known' point in time. Hence, there is an implicit coupling built between your client and server components. In other words, it can be very difficult or just impossible to build a new client to consume your services.

The most common and fatal mistake developers tend to do is to 'leak' implementation details of a service through the API interface. In other words, they design API interfaces more as ways to implement technical tasks rather than fulfilment of functional needs.

For example, let's assume you are building a service to enable a 'buyer' evaluate his 'vendors' each day. Vendors can make submissions one or more times a day. The buyer then evaluates the submissions and selects a vendor each day. The following could represent a set of RESTful API end points for this requirement:

Say, there is a new requirement to exclude a vendor's submission during evaluation. Also, it should be possible to undo this exclusion.

The first naive attempt is to implement the requirement as shown:

The API doesn't reveal the business intention clearly to a consumer. We are asked to exclude a vendor's submission explicitly. Can we not create a new end point that represents this requirement ?

We now have two end points leveraging the HTTP POST and DELETE methods - one for exclusion and the other for undo exclusion.

By thinking in terms of the business functionality, the end point has become more meaningful than just a projection of a technical implementation. Writing APIs that leak the internal technical implementation/state can make it difficult to understand and maintain them. They also increase the coupling between client and server components making them less independent and flexible.

Each end point should have a business meaning in your application. Here are a few points to enable cleaner API design and modelling:

1. Think in terms of business actions; not the underlying state based actions in your client - server implementation
2. Create end points with single responsibility; the underlying logic can still be reused across end points
3. Separate end points for each user role if it aids better clarity

In my next blog, I will describe similar issues when building an API based client server workflow application.