The API Lifecycle

This lifecycle was created by the OpenAPI Initiative to explain how OpenAPI can be used throughout the development and deployment of APIs:

Providing and using an OpenAPI Specification (OAS) document is not, however, a point-in-time activity. It is fundamental to the API lifecycle, providing affordances for all activities from the inception of the design right through to deployment and support. If an API lifecycle is a transport network then OAS should be considered an arterial road, providing the means to efficiently transfer large amounts of pertinent information quickly and efficiently.

When one considers the API lifecycle it starts to become clear how useful an OpenAPI document is. Consider the simple API lifecycle below. It is based on the idea of API-first design, where the interface is designed without writing a stitch of implementation code. OAS can be used at each stage in this lifecycle.
An API lifecycle within an organization clearly has more nuances than the steps described above, and will undoubtedly be tailored towards the software development lifecycle in use. An agile methodology may, for example, iterate over the steps shown above many times. However, for the purposes of exemplar this simplified view has merit as it shows the utility of OAS at each stage.

Using OAS to help elicit requirements
The first step in our conceptional lifecycle is Requirements, where ideas about an API start to take shape. “Taking shape” covers a multitude of different activities – some technical, some not. Requirements gathering in most organizations stretches back into the business, working with the product team to define what the API should provide for its consumers and that support a holistic view of the product features.

Technologists working on bringing those requirements need some means to convey them. OAS provides the means to support this in an agnostic and portable way. It also provides the means to do this quickly and be able to socialize their ideas with other stakeholders with minimal set-up.

Having a sketch of your API design in OAS when gathering requirements gives you a headstart when starting design.

OAS in development
Once an API design has been created the time has come to write some code and create an implementation of that API in software. Acting on the output design process means working with the OpenAPI document to help bring your application to life.

Our conception lifecycle assumes an API-first design approach, where the OpenAPI document is created upfront and code is then written to create the implementation. There is, of course, the “code-first” approach where the implementation is created and then (typically) annotated so an OpenAPI document can then be generated.

The pros and cons of both approaches are beyond the scope of this post, but if you take the API first approach then having the design detailed in an OpenAPI document is critical to your implementation. The OAS has a rich tooling ecosystem and using the OpenAPI document to generate server-side code is a common approach to automating the creation of controller classes. This speeds up the delivery of the implementation and helps ensure the interface design and the implementation are closely-matched.

Implementing your API in code is, however, only one of the subsequent steps in the lifecycle. Other activities rely on OAS to be completed successfully.

Comments

[HERI WAMBO]

Good article

[mahir dasare]

Thanks for feedback