Avellas Guide to API: the do’s and dont’s for building modern API’s

API’s is an essential component in the work we do in order to make different information systems communicate with each other. Experience from integrating a multitude of systems gives us unique insights into what strategies work and which does not. The strategies and points outlined in this article are essential for your company to succeed with your API Implementation.

Governance: API Task Force

Before your company starts developing an API, it is imperative that you choose to involve the right people. But who are the right people you might ask? That depends on the problem your API is trying to solve. Avella categorize APIs into two groups; business oriented and IT oriented

When developing a business oriented API you should involve people from both business and IT. This is to ensure that the API’s you are developing provide value to the end user.

An IT oriented API is usually created to provide communication between several systems on your comapany’s backend. In these cases you should involve people from the system that is providing the API, as well as people from the system that is going to consume the API, ensuring that the needs of both the provider and the consumer are met.

After you have selected the right personnel, you can begin building your API’s. When the API has been developed, you should make sure that the API-task force persist in some kind of form. This to ensure that the intellectual capital your task force has accured during development does not disappear. If you are going to make changes to the API or develop new ones within the same domain, you don’t want to start from scratch.

CRUD

When creating operations for APIs, you should make sure each operation falls within one, and only one, of the categories within the CRUD principles. The acronym CRUD refers to the four basic functions of persistent storage. CREATE-operations should deliver information to the system. READ will get information from the system and deliver it back to the user. UPDATE will alter existing information. DELETE will remove information from the system.

But why should I do this? You might wonder. This is because chances are you are going to create a RESTful web API, and the protocol you use to communicate with an web-API is through the HTTP protocol, which has header elements that are directly applicable to the CRUD definition.

If you do not adhere to these principals it will negatively impact the end users ability to understand and utilize the API efficiently.

Versioning

When should you create a new version of the API? At Avella we create a new version of an API when the name or a field has been altered, the functionality of an existing opereration has been altered so much that it no longer performs the same task or when you have added new fields to an operation that is required by the operation to function. We only have one simple rule, and that is, if the change you have made to the API does not break the functionality of the consumer, you should not create a new version.

Minor versions is not a consept the consumer should need to be aware of, only a consept the developers need to know about. When you create a new version however, the consumer of the API will have to be informed that there now exist a new version.

When you release the new version it should be made available on a different endpoint. Doing so will ensure that the old version doesn’t disappear and break the consumers’ code. Both versions should be kept available for a while in order to give the consumer time to adopt the new version of the API.

Documentation

The documentation of an API is as important as the implementation of it. If you do not provide sufficient documentation it will provide very little value to the end user. Every API documentation needs to contain a description of all the operations that include input, output and eventual error messages. Together with this documentation there should be a machine-readable interface e.g an open API specification which is generated based on the API implementation. This specification is very important because it provides the end user with an always up to date version of the current API. Without this specification, the only thing the user can rely on is the manually made documentation, and based on experience it is hard to keep it up to date at all times.

Consistency

This section was originally going to be called “naming”, but we decides to call it consistency instead. The reason for this change is that there are countless different naming conventions out there. Which of them you choose to use when making your API is not important, however to stick with the one you choose in the beginning of the development process is. Consistency is one of the most important factors in making your API easily understandable. If you do not stay consistent in your naming it will lead to problems for both your end users and the developers. A consistently named API will be considerably easier for someone who were not in the development process to understand.

Choose The Right Platform

At Avella we have chosen a platform driven approach to integration. The reason we use a platform is that it makes development simpler, as well as provides tools to help you create documentation, validating incoming requests and security. You can implement all these features on your own, but with the use of a platform you can give yourself time to focus on what is important and that is developing quality API’s that provide value to your organization.

Closing Remarks

Creating API’s in itself is not a difficult task. The difficulty lies in making an API that actually provides value to your organization and your customers. If you gather the right people, keep your operations within the CRUD definitions, keep your API documentation fresh and stay consistent when naming your resources, chances are you will succeed in the implementation of your API strategy