At some stage, usually after haggling the estimated cost and time, business will reluctantly accept the proposal and authorize the API development to commence.
As noted I have broken down the extensive life cycle in to various stages and thus the image on the left is representative of the activities undertaken during the development of the API. In the next section we will discuss the testing and deployment.
Detailed Requirement Analysis
In the previous section we gathered a preliminary list of the requirements in order to derive sufficient information with which to compare to the API catalogue and with which to use as inputs in to the gap analysis. As the process of analyzing requirements can be a time consuming and extensive task it is usually included as a chargeable item to the business as it requires, in most cases, a business or systems analyst to undertake the activities. Therefore it is essential for the requirements and their analysis to be expanded upon by suitably skilled persons.
API Specification Design
The output of the detailed requirements analysis will provide a number of essential items to be used in the subsequent stages of development. For one the analysis will contain essential information on the systems or platforms which the API needs to access as well as the critical methods or functions to invoke in order to access or transport information. At other times it may include documents and information gathered from vendors or other teams which would (hopefully) neatly spell out the required processes and means required in order to access the intended endpoints.
In doing so the initial stages of the API’s ‘live documentation’ begins to take shape which will later be added to the API catalogue for further reference by developers, engineers and support teams. Designing of API specifications is an entire topic on its own but for the purposes of this article it would describe in some detail the exact way to invoke the API and its instruction set. To this extend the specifications will outline information such as the method (GET, POST, PUT, DELETE), the endpoint URI (for example, /v1/order/new) and the parameters to be supplied in the request body as well as their description and other supplementary information.
Further the specifications would also outline expected responses whether good or bad and in both cases describe the expected output and information.
The best specifications or those who take pride in their specification design will often include example requests and responses so as to demonstrate the API.
Forward Integration Testing
Often the case will be that the API needs to access a back-end system or third-party system in order to gain access to functionality required during its orchestration. For very good reason these systems are usually secured by firewalls or other mechanisms to prevent unauthorized access.
The process of forward integration testing is to ensure that a clear corridor exists between the API and the intended endpoint so that no obstruction exists during development, staging and production. At its initial stages access will most likely be established between the API’s development environment and a similar development or testing environment of the respective endpoints.
Once this is complete and correct operation is established development of the Southbound interfaces can occur.
API Northbound Design and Seeding
Very often a number of activities will run in parallel usually influenced by other upstream activities. For example there may be another team developing web front-ends or mobile applications which require access to the API as part of their process and similarly on the Southbound a vendor may be implementing a new system with which you need to access and therefore the development of an API is very much an exercise in fluidity and patience.
However one can greatly assist the process by first designing the Northbound interfaces as per the specifications and then seed it with static or simulated data. To the upstream developers this would allow them to invoke the API to simulate and test its methods and use the data in their application or mock-ups.
API Southbound Design
In parallel or shortly after the design of the Northbound interface and Southbound interface facilitates the API’s access to back-end or third-party systems and provides the API with the ability to access and transport disparate information.
As an interface is brought up it is brought in to the overall orchestration systematically and progressively until all interfaces have been completed.
At the conclusion of this stage the API should resemble the requirements and specifications as desired and is now ready for testing.
Depending on how the API was designed, whether on an API gateway or a physical server, a process usually exists to promote or move the API in to a suitable environment for testing. This is essential because development environments are usually ‘dirty’ (uncontrolled) and not of suitable capacity for testing.
Testing is a destructive process and as described in the following section requires a specific environment.
Up Next: Testing and Deployment