An API ( Application Programming Interface) is a powerful technical and business tool whose good use can result in tangible benefits for the organisation. This is because IT infrastructure that has been closed until now, opens up to external systems, enabling orderly, safe and efficient interaction of data directly affecting the company’s financial results (e.g. orders).
In this article you’ll learn:
the definitions of the API Lifecycle and API Design
the characteristics of the particular API Lifecycle stages
examples of tools supporting activities in the specific areas
The implementation of a good API isn’t a simple task. It requires separate and autonomous software components. During the development of the given element , many criteria with a direct impact on the future functioning of the API have to be taken into account.
The whole process of work on an API – from the idea to the withdrawal of its given version from use – is called the API Lifecycle.
The preparatory phase during which all areas of its future functioning are analysed in detail and defined in these fields is called the API strategy. Due to the importance of the preparatory phase, we’ll arrange a separate publication containing of all the necessary aspects in the process of formulating the strategy.
The stage after determining the guidelines and before implementation is called API Design. And this is what I’m going to cover in this post.
The first stage of creating an API project should be a reliable analysis of its business usage scenarios. As a consequence, all use cases with the new service in the lead role. The information collected that way will allow work to start on determining the structures of the supported data, the operations that can be called, and a list of possible service responses.
The design first approach
During this process, the “design first” approach is recommended. It consists of creating a detailed API Design that can be used later during implementation. It actually reduces the workload.
What needs to be done before implementation
An additional advantage of API Design is the ability to provide an interactive console that is a mock of the designed service that returns its sample answers. It’s important that this step takes place entirely before implementation, enabling collection of opinions and tips as early as in the analysis stage.
Such information can be translated into iterations ,correcting the project until it’s satisfactory.. Then, the approved form of the documentation will be used for implementation, which will reduce the risk of introducing possible corrections of the source code (and incurring related costs).
What are the best tools you should use?
The most popular tools thanks to which API methodology is possible are the RAML language and the OpenAPI specification supported by Swagger.
Acquiring them isn’t a difficult task even for people without advanced technical skills , as to make things easier these solutions support the users with prompts and validation of the interpreted syntax. These tools usually have a great ROI, as once deployed they can deliver measurable business benefits.
API development itself should be performed as efficiently as possible to reduce its time to market. The ease of transferring the design of a new service described in the previous point to its actual implementation is of great importance here:
from the Mule data bus design, the RAML specification is directly imported initiating automatic development of the components for communication with the API and the application template,
SDK elements generated from the API documentation created in Swagger may be used in the implementation of communication in various integrating tools.
In addition to the smooth translation of the project into production, it’s necessary to use a proven set of practices, procedures and methods related to the implementation itself – e.g. the Continuous Integration tool (e.g. Jenkins), a source code repository (e.g. GIT), division into dedicated environments and a tested workflow.
Testing the process
From the point of view of the developing and testing process, API should be treated like any other application. This means that testing should also be carried out in a reliable way that , embraces all the necessary aspects – functional, performance and security.
Depending on the needs, tests can be carried out manually, automatically or using a mixed method. N.B. only performance tests can be automated.
A well-tested API needs meet the expectations of potential consumers as well as be implemented into the IT infrastructure of an organisation. As a result , it can start being used on the productivity and start bringing the expected benefits.
The implementation procedure must be precisely planned and documented in a way that takes into account its impact on the other components, the implemented business processes, and security.
It’s also important to effectively inform future users about the new service and its functionalities. API Management tools are helpful in this matter. Apart from publishing the API documentation they can also help to spread the details of the service for instance in the related social channels, such as online forums or comments sections.
Security and access control
Other important aspects related to the business use of API are security and access control to services, but also monitoring their usage and managing changes in their configuration. I’ll tell you about them in the next post, in which I’ll also discuss the equally important issue of versioning and withdrawing API from use.
Meanwhile, if you’re interested in API, be sure to read our previous posts: