After having discussed what an API is and what an API does we can now extend our understanding towards the life cycle of an API. In this article we will focus on how an API progresses from ideation to operation.
This article is part of the ‘Essentials’ series and focuses on the ground-level understanding required to undertake the journey in to the world of APIs and will through the course of the series build upon your skills and introduce you to core concepts. This series is intended for people who wish to gain a rudimentary understanding of APIs such as students, new software developers and managers wishing to gain understanding and experience within their team.
As with any design be it a house or an API a defined sequence of steps and gates must usually be followed in order to give rise to the creation of such. Just as a house cannot exist without an architectural blueprint so an API cannot exist without design specifications. Software developers know this problem well and today follow some or other variant of a Software Design Life Cycle (SDLC) to progress the software from its ideation stage through to final release.
In a similar fashion an API follows a design life cycle and as a piece of software itself is fairly similar to that of the SDLC. In this article I have outlined an API life cycle I had developed over many years and implemented in a number of busy divisions and departments. The terms have been simplified in line with the basic nature of the ‘Essentials’ series and may be referred to by other names however their nature and purpose remain static.
An API and to a larger extent just about anything under construction originates with requirements that when translated become a design and eventually, after many hours of work, in to an actual finished item.
On the left is a representation of the essential sequence of steps invoked during the requirements gathering stage of API development. Different organizations and teams may have other steps depending on their needs but this is a good starting point if one is venturing down the path of understanding or beginning from scratch.
New API Request
Typically I prefer that whoever requests a new API to be developed accomplish an on-line form or some form of documentation which requires them to specify a certain amount of detail such as use-cases. Often I find that it forces the person to sit down and carefully think about their requirements as they pertain to their project or intended purpose. This works significantly better than being ambushed in the corridor with a ‘Hey, we need a new API…’. Usually the form would ask for the requirements, intended endpoints (back-end systems or third party providers), required delivery times and other information. In a later article I may post such a form as a starting point.
A form can contain only so much and although it is an essential part of the process not every person who completes the form is going to provide the same level of detail. To this extent I generally use the ‘New API Request’ as a trigger to initiate a meeting where the relevant people can be assembled and productive discussion can take place on the nature and purpose of the API. I always believe it is essential to be visible and this provides a fantastic opportunity to meet and interact with other areas of the business.
API Catalogue Review
In organizations that value their time and productivity a system usually exists with which to catalogue existing APIs. At a most basic level I have seen organizations make use of an internal system which supports the creation of documents through collaboration (such as a WIKI) and others have deployed more purposeful systems. The most critical aspect to bare in mind is that APIs are encapsulated within live documentation which needs to change and be published and referred to often. For this reason keeping API documentation and catalogues in Word, PDF or other static forms of documentation is strongly discouraged.
The purpose of the API catalogue is to keep a record of the existing APIs either in production, under development or archived so as to evaluate the new requirements against the existing APIs. In organizations where APIs are plentiful the catalogue would contain a comprehensive list of existing endpoints accessible and existing methods and functions available for reuse.
This is the crux of the API catalogue – to make use of existing functionality and prevent duplication.
API Gap Analysis
After review of the API catalogue a best case result is where an existing API would satisfy most, if not all, of the requirements. Were this the case the development teams would be able to accommodate additional development as a low risk or low modification change – a great result.
In reality it is rarely that simple. In most cases additional development would be required in order to have the API satisfy the requirements which could vary from straightforward to hell-on-earth (* not a technical term). Thus the practice of a gap analysis is undertaken so as to carefully understand and outline the sequence of events required to realize the desired API functionality.
API Cost and Time Estimate
To make changes to an API or to add additional functionality will undoubtedly require time and as they say – time is money.
In practice the gap analysis and cost estimates are usually compiled in to a single document and passed back up the chain to the business to feed in to their project budgets and decide whether the cost is viable and what the impact would mean to other lines of business.
At this stage the initial requirements gathering stage is complete.
Up Next: API Development