What is API Modeling & Profile?

Overview

The tracer bullet term describes the use of code as a way of exploration and risk reduction. Tracer bullet code delivers value through learning rather than through production-ready code.

API modeling is a tracer bullet for API design. It is a technique for exploring the necessary elements of an API before the design and delivery process. API modeling helps to bring together the insights and artifacts from the previous steps into an API profile that describes the scope and intent of the APIs needed to deliver the desired outcomes of end users.

What is API Model?

Just as Web design begins from a wireframe, a great API design begins with an API model that helps define its scope and responsibilities. The goal of API modeling is to fully understand and validate the needs of developers and end users.

Unlike a wireframe, which focuses strictly on end user interaction, API modeling focuses on both developer and end user goals. Often, these goals are aligned, but sometimes they are not. API modeling helps to surface issues quickly so that they may be resolved prior to writing code.

API modeling uses job stories, activities, and activity steps as inputs to produce a cohesive view of each API, called an API profile. An API profile captures characteristics about the API, including its name, scope, operations, and emitted events that will be used to deliver desired outcomes. API modeling is done before designing and developing begins — while the cost of change is significantly lower.

After completing API modeling, teams will be ready to migrate the API profiles produced into an API design. API modeling can be used as input for a single API design style of choice, such as REST, GraphQL, or gRPC. It may also be used to inform the design of an API that uses a combination of these API styles to support the various digital channels for customers and partner integration needs.

API Profile Structure

API profiles capture all necessary information about an API, independent of the API style or styles that it will expose (e.g., REST and GraphQL). The API profile is used to drive the design of an API, but also provides the beginnings of the API documentation effort during the early stages of API definition.

An API profile captures the following details about each API:

• The name and a short description of the API
• The scope of the API (internal, public, partner, etc.)
• API operations with input and output message details
• Participants allowed to perform each operation, in preparation for securing the API.
• Events generated by each API operation, to drive extensibility beyond the API’s original intent.
• (Optional) architectural requirements identified, such as a service-level agreement (SLA)

A spreadsheet or document is sufficient to capture each API profile. Using a collaborative spreadsheet allows teams to capture and refine API profiles without the need to email changes among team members. Some teams prefer to use tools such as wikis for capturing API profiles.

Source: Principles of Web API Design by James Higginbotham