How much does your API cost to maintain?

[#1]

It has been found that typically the cost of maintenance of any software constitutes more than 50% of all SDLC phase costs. There are many reasons for this exorbitant cost of maintenance of software and one of the major reasons lies in the design approach of the software.

Therefore, in this article, we will touch upon certain key aspects of design that help in lowering the maintenance cost of APIs.

If taken care of in an effective and planned way, the following attributes would surely contribute towards bringing down the maintenance cost of APIs.

Minimizing human intervention: It’s always better to make use of efficient automation tools and/or methodologies around us to perform regular and repetitive jobs in API SDLC.

The first and foremost factor is to use the CI/CD tools as much as possible. From a development and deployment point of view, the frequent and effective usage of a CI/CD framework, along with efficient source control and build automation tools, would definitely reduce the cost to maintain APIs to a great extent by removing the frequent development and deployment bottlenecks.

Similarly, there are many test automation frameworks available, which could be used during API test phases like Regression, Load and Performance, Stress or Soak. The effective use of Test Automation in the context of API testing would lower the maintenance cost of APIs to a great extent.

Segregation of Code and Configuration: Like any other software design, the segregation of code and configuration should be maintained.

In the context of API design, it’s always a good practice to design the Northbound and Southbound interfaces in a more generic way. That means, the details of the IP, Port, Path and other useful parameters, needed for the API to work smoothly should be kept configurable as much as possible.

Additionally, the parameters needed at runtime should be configured in the cache or key value maps or in some persistent data store.

Moreover, in a generic sense, APIs should be designed in a flexible way as much as possible. It means that APIs should be designed in such a way that without code changes the API would behave differently against different input stimuli based on some configuration values.

All these steps guarantee that APIs need not be changed every time there is a change in environment parameters. Moreover, if the set of configuration values are maintained per environment, then it would also be possible to deploy the same code base across multiple environments without even touching the code.

Additionally, it is also beneficial to use replacement plugins of build automation tools to replace a specific code snippet during deployment phase across environments. With this step, the same code can be maintained for all the environments even if there is a need to have slight differences in code across environments.

Reusability: One of the most common practices to keep the development and maintenance cost at a lower value is to use the reusability concept.

In terms of APIs, the commonly used steps across the majority of APIs, the fault handler and/or the generic response framework, can be clubbed together and maintained as a common part.

This common piece of code can then be deployed independently as a standalone API and the same can be called at runtime from the consumer API, provided the context switching does not contribute to significant performance degradation or increase in latency.

Otherwise, the piece of code can be placed in the single executable API during the deployment using the deployment automation tool using some replacement plugin(s).

As a result of this approach, the changes required in the common code (due to the need of bug fix or interface change) would need to be done only at a single place contributing to a significant decrease in API maintenance cost.

Consistent RESTful API Design Pattern:

There is a great need to adopt to the consistent RESTful API design pattern across an organization’s APIs so that API consumers have the same experience when consuming any of the APIs. An ‘Ideal API’ should cater to the RESTful constrains which is defined along with their benefits as follows:

1. The Uniform Interface constraint illustrates the need to have an uniform interface between the client and server. Such an interface actually enables each part of the API to evolve by its own by simplifying the API itself and decoupling the whole architecture.

As per Roy Fielding’s assertions, there are four key principles to design an API with Uniformity of Interface in mind. These are Resource Based Design, Manipulation of Resources Through Representations, Self Descriptive Messages and HATEOAS.

2. The Stateless constraint is the Key to RESTful API design. In REST, the client needs to include all the information for the server to fulfill the request, resending state as necessary if that state must span multiple requests. This would actually cater to greater scalability of the API, because the server does not have to maintain or act on the state.

3. The Cacheable constraint defines the capability (or no capability) to cache responses. That means the responses must define if they are cacheable or not. This would prevent the clients from reusing the inappropriate response data to further requests. The proper ‘Cache-Ability’ would eliminate some client-server interactions, improving the scalability and the performance of the API.

4. The Client-Server constraint talks about the benefits of separating the clients and servers through an unified interface. For example, the clients should not be concerned with data storage, which would make sure the improved portability of the client code. Similarly, the server should not be concerned with the UI, resulting in their simplicity and scalability.

5. The Layered System constraint illustrates the way a client consumes the services of the server. It’s so possible that the client is connected to the end server via a series of intermediary ones. These intermediary servers may improve system scalability by enabling load balancing and by providing shared caches. Layers may also enforce security policies.

6. The (optional) Code on Demand constraint depicts the possibility of temporarily extending or customizing the functionality of a client by transferring logic to it that it can execute. Examples of this may include compiled components such as Java applets and client-side scripts such as JavaScript.

Complying with these constraints, and thus conforming to the REST architectural style, will enable the API to have desirable performance, scalability, simplicity, modifiability, visibility, portability and reliability.

With the design guidelines stated in this article along with proper and in-depth testing across environments, adherence to standard code nomenclature and principles would make sure that the cost of maintenance of the API is as low as possible.

[jonesfloyd]

+1 on @Dom Couldwell's comments. Gave it a quick read, and it flows well. Feel free to move this to the proper forum when ready.