API Development Workflow

Development flow

As a product manager, we'll be focused on the API product life cycle. However, there are a number of steps within the technical requirement gathering, design, development, and test phases of the API product life cycle that each API goes through at an engineering level within an organization before APIs are ready to be distributed to users. These steps form the API development workflow.

In an enterprise setting, when a product manager presents a proposal for an API, the engineering lead augments the business requirements with technical and security requirements for the API’s development. The engineering team also identifies the right workspace for the API and sets up source control before the development begins.

The process that engineering teams use to make APIs is shown in the following diagram. The API development workflow includes a number of tools and technical stakeholders across the stages of definition, design, development, testing, security, deployment, and observability. Once the API is ready for users, it is distributed.

Once our API proposal has been reviewed and approved, we'll work with the software architects and developers on our team to get the API into the design and development phase. Product managers aren’t expected to be too involved in the development process, but it’s important to know how engineering teams work so we can work with them effectively. Familiarity with the API development process, the tools involved, and the stakeholders will help us navigate cross-team communication and manage stakeholder expectations.

Let’s now discuss in more detail the eight stages of the API development workflow shown in the preceding diagram.

Definition

The definition stage involves the product manager working with their engineering leads and software architects to put together the technical, business, and security requirements for the API.

At this stage of the API life cycle, operations are specified. This lays the groundwork for designing and implementing an API efficiently and provides a central location for all API-related information.

Make sure to establish who in the team will move the API through all stages of its life cycle, defining who is responsible for each phase of producing an API.

Setting up a separate workspace for each API makes sure that there is a single place to find everything that is being worked on during the development life cycle. With a dedicated GitHub repository for a given API, all the code, pipelines, problems, and other supporting features can be managed from one place.

Design

Software architects review proposals for new API designs and generate the API contract. These API contracts can be used to generate preliminary documentation and mocks using tools such as Postman. This provides an early view of what the API will look like.

The design phase of the life cycle establishes a formal process and approach to developing an API, ensuring that APIs are designed using established industry and organizational patterns and known practices for defining the API surface area and behaviors.

The OpenAPI Specification provides a uniform vocabulary for specifying request and response APIs and webhooks, ensuring API providers and consumers are on the same page. It helps stabilize the API life cycle by providing a contract for documentation, mocks, testing, and more.

A mock server helps duplicate an API’s production capabilities before any code has been written, making APIs more concrete and real earlier in the life cycle. This helps teams quickly develop APIs that satisfy everyone’s expectations, offering useable elements for design, documentation, and testing.

Development

The development stage refers to the actual setup of the API server and gateway. PHP, Python, Ruby, .NET, C#, Java, and Perl are all API languages. Coding and testing may require revisions, but developers shouldn’t deploy an unstable API. API development requires planning, coding, testing, and the discipline to limit customer-facing API modifications.

API development can be done by a single developer or a professional ...