API Design Checklist

Brought to you by Stoplight.

10 essential steps for a scalable API strategy

Curated by API Experts

1 Sketch Ideas & Gather Requirements

SUGGESTED TOOLS

Strategize: Define the goals you want to achieve with your APIs. Miro
Specify which markets you need to address, which resources you
Notion
have at your disposal, and the time frame you have to achieve your
goals. Productboard

Tip: Always plan for your API to be external even if it’s internal to start off with Good Ol’ Whiteboard

Research User Needs: Collect jobs to be done , described in very

non-technical terms. You can collect from the following folks:

- Customer Support for problems relating to the topic at hand

- Product for insights from tools

- API Client Developers for relevant problems they’ve had

- End Users to understand common use cases

Sketch: With a better idea of what your users are going to be doing,
it’s time to grab a whiteboard, or a collaborative sketching
application, and get to doodling this API. Some options are :

- Entity Relationship Diagram

- Data Flow Diagram

- Sequence Diagram
Tip : Keep implementation details out of the sketch phase as much as possible
2 Search Reusable Designs in Catalogue
SUGGESTED TOOLS
Explore Existing APIs: Duplicate services lead to inconsistencies
Stoplight
and wasted time.

Postman
Look for existing APIs in your catalogue that solve for a similar use In-house Solution
case. Reuse the parts you can, and only build what’s unique and
required.
Tip: DRY (Don’t Repeat Yourself) anywhere. Stick to this across the lifecycle

Find Reusable Models: Now that you have your requirements in

order and a list of services that you can reuse, it's time to think
about the resources that need to exist. Find models that can be
reused or repurposed for your use case.

e.g. We need a Passenger resource, so search for an existing

Passenger model. Can’t? Find a Person model, maybe we can
repurpose it.
3 Create an API (OpenAPI, AsyncAPI) Spec
SUGGESTED TOOLS
Title and Description: Choose a name that follows your
Stoplight Studio
organizational guidelines. You need to make it discoverable.

VS Code
- Explain the purpose of the API well

APIBldr
- Think about what you will search if you were looking for a similar

API

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 Models and Endpoints: Reuse models and endpoints that you
discovered in Step 2. Follow similar naming conventions and
guidelines for new models.
Tip: Consistency is key

4 Lint Against a Style Guide

SUGGESTED TO OLS
Have an Existing Style Guide? Lint against it. Make sure you have
Spectral
no errors. Warnings and info messages should preferably be non
existent or as little as possible. OpenAPI-CLI

No Style Guide? Create one. It’s an automatic set of guidelines that

you can automatically validate against.

Tip: Remember consistency is key

5 Push to Git
SUGGESTED TOOLS
Choose an Approach

Stoplight
Design Repo: A seperate repo for design and documentation GitHub
artifacts.

Monorepo: One project, with a directory for each API which contains
the source code and API description.

Multirepo: One project for each API which contains the source code
and API description.
Tip: Git will become your source of truth and integrate into your dev workflow

6 Generate Docs
SUGGESTED TOOLS
Generate API Reference: Show developers how to move from
Redoc
documentation to code. All your endpoints and models are
documented here.

Stoplight
Swagger-UI
Write quick start guides and tutorials: Guides on popular use cases
to help developers get started quickly.
Note: We have a documentation checklist coming soon. Stay tuned!
7 Generate a Mock API

SUGGESTED TOOLS

Generate Mock Server: Use your OpenAPI to generate a mock

Prism
server.

Mockoon

- Give users feedback with a lifelike API mock

- Speeds up development

8 Get Feedback from Stakeholders

SUGGESTED TOOLS

Share documentation and mock servers with stakeholders:

GitHub
Preferably have the generated docs and mock server in a single url

to share with all stakeholders. Stakeholders can include:

Stoplight

- End Users

- Product Managers

- API Design Reviewers

- API Gatekeepers

- API Center of Excellence

- Architectural Committee
9 Iterate till you have Consensus

RECYCLE
10 Handoff to Developers
SUGGESTED TOOLS
Share with Developers: Share generated docs and mock server in a
GitHub
single url to share with developers. This includes producers and
consumers. 

 Stoplight

Use OpenAPI for Contract Testing: Use a mock server generated

from OpenAPI as a validation proxy to make sure APIs are being
developed according to the spec.

Develop in Parallel: Let frontend and backend developers build in

parallel as you have a contract that the API is being built against.
MORE CONTENT FROM STOPLIGHT

API Design Whitepaper API Documentation Checklist

Leverage API Design-First and API 10 Essential Components of API Docs.

Documentation to Drive Business Agility Guide to building a winning DX.

Download Now Contact us

API Design Checklist

Want to talk API Design? Contact us
Brought to you by Stoplight.