A Practical Guide to API Design-First

In the past, businesses only had a few APIs, which made it very easy to manage and change. They were mostly driven by developers who would jump straight into code. Today’s competitive world where agility is king, requires hundreds or even thousands of APIs to keep up.

The increase in competitiveness and revenue tied to APIs have brought quality design and developer experience to the forefront. Today, leading organizations start with API planning and design when implementing APIs. This approach is called API Design-First, sometimes also known as API-first architecture, and it’s the way to go for your API architecture.

Why API Design-First?

Design-First means everyone on the team is speaking the same language and should be an integral part of the API workflow. Companies and teams that embrace this approach can bridge the gap between business and technology. There are many benefits to this style of API development, including:

• Customer-Centric APIs: Product managers and business leaders are involved earlier in the process to help shape the API’s features. This helps the team build APIs with customer requirements at the forefront.

• Design-Driven Development – API developers can use the API design to drive their development efforts. Automated tools can guide them on what to build and make sure they’re building the API according to the design.

• Rapid Feedback – Review and validate designs by trying out a mock API and its documentation rather than waiting until developers deliver code.

• Parallel Development – Consumers can start building API clients before the API itself is finished by consuming mock APIs. This allows API consumers, API producers, and technical writers to work in parallel rather than waiting on each other.

• Reuse Existing APIs – Putting thought and time in the design phase means API designers and developers can explore their existing portfolio for reusable designs and best practices. Design-first greatly improves API reusability!

• Consistency – Automatic Style Guides and existing API designs ensure APIs across the organization provide a consistent developer experience.

  Check out this API workflow diagram, one of my favorite API memes to better understand this.

API Design-First Workflow

Postman’s 2020 state of the API report identifies more than 87% of API practitioners working toward an API Design-First approach ( Which is amazing! ), but also observes the general lack of consensus or understanding, if I may say, of what API Design-First actually is. Let’s dive into an API design example and API-first principles.

I decided to dive deep into what API Design-First workflow looks like using Stoplight and GitHub – the widely used version control system in this webinar.

Lets dive into a step-by-step breakdown:

Log in to Stoplight Workspace

Workspaces in Stoplight provide a home for all your internal and external APIs to promote collaboration, visibility, standards, and reuse of artifacts. If you don’t already have a workspace, you can create one here.

Create a Git Repository

• Team Member: Product Manager / Product Owner / API Architect
• Artifact: Git Repository

Almost all software teams use a version control system to manage their software development lifecycle. Managing API designs on your version control helps bridge the gap between design and development, integrate into existing workflows, and keep a single source of truth. In the later phases of the lifecycle, you can integrate other tools like code generators or testing tools as part of your CI/CD pipeline using a Git repository.

Create a blank project in Stoplight and promote it to Git. This Git repository would be home to all API artifacts for this API.

Plan

• Team Member: Product Manager / Product Owner
• Artifact: API Requirements Document

The first step before even jumping into creating an API specification document is to create a requirements document / API charter. This ensures the architect/designer creates designs with consumer needs at the forefront.

Create a Requirements Document

Define Why

We don’t just build APIs for the sake of it anymore (hopefully), there must be a reason we are building this API. Define what the problem is at a very high level. Maybe there is a technical problem with a poorly written old system. There could be a functional requirement like adding monthly subscriptions to a donations system that previously only handled one-off payments, or something even bigger.

Identify Audience

APIs can be consumed internally by your team, other teams in the organization, or by external developers. It’s important to identify the consumers and adding them to this requirement doc to help navigate the process later.

Add User Stories

Collect the Jobs To Be Done, described in very non-technical terms. These stories are used to design API Specs. This information can be gathered in various ways:

• Surveying end-users to ask what use-cases they have
• Asking Customer Support for problems relating to the topic at hand
• Consulting Product around insights from tools like Productboard
• Asking API client developers about relevant problems they’ve had

Turn these into user-stories and add them to the requirements document.

Create Wireframes

Create low-fidelity mockups of how you envision the API is going to be consumed on the client-side. This guides designers and developers on usage and thus design accordingly.

Add Data Models

While this will be refined in the design phase, adding domain models to the requirements document sets guardrails and direction for the designers creating API specifications. Alternatively, some other options are to represent APIs in a simple diagram. Some options are:

• Entity Relationship Diagram
• Data Flow Diagram
• Business Capability Model

Push Changes

Much like a normal software development lifecycle, create a branch for each new addition. For this step create a branch for the planning phase e.g. feat/plan. Once ready, push your changes.

Next, create a pull request from GitHub (Or a version control of your choice).

Review & Merge

Get other stakeholders like PMs, Architects, core consumers etc. to review the requirements, leave comments on GitHub where required. Merge the pull request when all comments are resolved.

Design

• Team Member: API Architect / API Designer
• Artifact: OpenAPI (f.k.a Swagger) Document

As a designer or architect, Stoplight Studio and workspace go hand in hand to help create quality API Designs. Workspaces come with explorer to search API designs across your organization while Studio is an intuitive UI editor to describe OpenAPI, JSON Schema, and Markdown documents. I prefer to keep both of them open in separate tabs to easily go back and forth.

First, review the requirements document in the workspace. Next, copy the API data model from the requirements.

Explore Existing APIs

Before jumping into creating the specification document, it’s very useful to explore existing APIs in the organization to ensure consistent naming conventions e.g. Pascal case vs Camel case and find reusable models e.g. Errors.

Consistent APIs = Quality Design = Great Developer Experience

Create API (OpenAPI Document)

Next, open up the project in Studio (in a separate tab) and create a new API.

• Give your API a human-friendly name (See how other APIs are named using explorer)
• Add a description – the purpose of the API. You can reuse the why section from the requirements document
• Set up security – It’s recommended to choose an authentication type that is already being used in other APIs in your organization. This promotes ease-of-use and consistency for developers consuming different APIs.

Create Data Model

Generate a model from the data model in the requirements document using Generate from JSON in Studio.

• Ensure property names are consistent with other APIs in the organization.
• Add additional properties like DateTime format for date properties. This ensures robust documentation and guardrails for developers producing/consuming APIs.
• Add a small description for each property. Technical writers can later build on this description.

Create Endpoints

Create operations based on the user stories.

• GET: fetch existing data (individual or list of items)
• POST: create new data
• PUT: update existing data
• PATCH: update a subset of existing data
• DELETE: remove existing data

Explore existing APIs for naming conventions. Ideally, you’d want to use nouns for resources i.e. /todos vs /getTodos.

Add a small description for each endpoint. Technical writers can later build on this description.

Reuse your Data Model for Requests and Responses

As you’re building out endpoints, you might require request bodies and responses to have different properties. Instead of duplicating the data model, reuse it by:

• Setting properties for requests only to be Write Only
• Setting properties for responses only to be Read Only
• Properties that should be in requests and responses should be Read & Write. (This is the default setting)

Reuse Components

Add additional parameters and headers like content-type, pagination, sorting, and filtering. Instead of duplicating these components across endpoints, you can share these components by creating a reusable version. Create reusable components where applicable for:

• Headers
• Parameters
• Examples
• Responses

Read more on shared components here.

Add Error Responses

Error models are usually consistent across different APIs across the organization. Look for an existing Error model in explorer. Copy it into your project to ensure consistency.

Create reusable error responses for common errors like Not Found, Unauthorized etc. from the error model. Add these responses to all endpoints.

(Roadmap update: Eventually, we want to add the ability to reuse models across the workspace).

Push Changes

For this step create a branch for the design phase e.g. feat/design. Once ready, push your changes.

Next, create a pull request from GitHub (or a version control of your choice).

I recommend adding a link to the workspace as a comment in the pull request, for reviewers to easily find documentation and mock servers.

Read more on API Design.

Create/Apply a Style Guide

While manually maintaining consistency is useful, Stoplight comes with automatic linting which allows creating/applying rules for common occurrences in your API. i.e. All my paths should be kebab-case etc.

By default, linting is done based on a predefined ruleset. You can add additional rules specific to your organization by creating a custom style guide. Some example rules can be:

• Enforce having at least one global security scheme

• Warn against using an authentication except for OAuth or missing descriptions

• Recommend having at least one error for Endpoints

These rulesets give you the ability to define and promote consistency across your organization automatically with flexibility.

Read more on Style Guides.

Review

• Team Member: Review Team & API Architect / API Designer
• Artifact: : Finalized OpenAPI (f.k.a Swagger) Document

Comprehensive reviews in the design phase ensure that problems are detected earlier and APIs are built according to consumer requirements.

Where to Review?

Reviewers should usually be looking at the consumer-facing documentation and generated mock servers to understand the consumer experience. This can happen within the Stoplight workspace.

Changes can be proposed in the pull request using comments.

Who Reviews?

If it’s a small team, then maybe another architect or designer reviews the design.

If there are 1,000 API developers then maybe you need a dedicated team. These teams have many names:

• API Design Reviewers
• API Gatekeepers
• API Center of Excellence
• Architectural Committee

Whatever size an organization is, developers alone should not be handling all reviews. Getting other stakeholders including business leaders, product managers, and clients involved with the changes that are coming, before they’re unleashed on the API ecosystem, can help increase morale, reduce code churn, and generally keep everyone on the same page.

Commonly Asked Questions

Does the terminology make sense?

Is the term “account” being introduced to describe users, when other parts of the API ecosystem at your organization use it for “companies” or maybe even financial reasons? Is there maybe a better term that could be used?

Are there breaking changes?

API reviewers will want to look out for changes that: remove endpoints, rename a property, change the data type of existing properties, remove enum values or any other sort of breaking change.

Is this consistent?

API consumers generally don’t enjoy guessing subtle differences between various APIs from the same organization, and they shouldn’t need to.

If one API uses JSON:API and another uses Siren, maybe that’s something to call out.

If one uses camelCase for properties and another uses snake_case, maybe that could be mentioned.

Spectral can help with a lot of this, allowing you to create style guides for workspaces. This will catch a lot of trouble sooner, but humans can still check the results after for anything which doesn’t have a Spectral rule.

Is this easy to implement?

Sometimes things are hard, but sometimes things are unnecessarily hard. If an API has been designed in a way that’s just going to be a nightmare to implement or involves making way too many HTTP calls to get a basic task done, this feedback can be made early on before more time and money is wasted.

Resolve & Merge

Make changes to the design based on comments within Studio. Merge the pull request when all comments are resolved.

Develop

• Team Member: API Producers & API Consumers
• Artifact: API Implementation & API Clients

With the design ready, the next step is to get your developers to start developing the API and implementing API clients. With a finalized contract both API Producers and Consumers can start developing in parallel.

API Producers and Consumers would consume the generated API documentation and mock servers to understand requirements.

API Producers

Generate the server-side code using a tool like OpenAPI Generator.

Set up a Prism proxy to automatically ensure the implementation is in line with finalized design.

API Consumers

Copy the mock server URL and code samples from the Stoplight workspace, to start developing clients against the generated mock server. Publishing the client is as easy as replacing the mock URL with the production URL when the API implementation is ready.

Document

• Team Member: Technical Writers
• Artifact: API Documentation

While the developers are developing APIs, technical writers can create a feat/documentation branch to start writing documentation.

What to document?

• Descriptions for all API design components in Studio
• Tags – Tags are used to group your models and endpoints (also known as operations)
• Real-life examples for endpoints
• Tutorials and How-to guides
• Authentication Guide
• Terms and Conditions
• SDKs – Use the OpenAPI spec to generate SDKs, using popular open-source OpenAPI Generator

Review & Merge

Next, push changes and create a pull request. Get other stakeholders like PMs, Architects, core consumers etc. to review the documentation, leave comments on GitHub where required.

Merge the pull request when all comments are resolved.

Publish

Once, the documentation and development phase is over, get ready to publish your API.

• Update the URL in the API design with the production URL for the API
• Update Mock URLs in API clients with production URL

Share API documentation with internal/external consumers from within your Stoplight workspace by changing the project visibility settings.

Your API is ready! Rinse and repeat for a new feature or version.

Watch the Webinar Video

Next Steps

Get started with API Design-First & a better API experience by creating a Stoplight Workspace here to be a part of leading API-first companies.

Found this useful? Share on LinkedIn or Twitter

Have thoughts? Reach out to me to talk API Design-First and all things API design books-related

Download API Design Checklist for a great API design document & for an API implementation guide

For more API lifecycle methodology, check out our API Design Hub.