API Design

Create thoughtful API designs that align with user needs, product goals, and consistent specifications.

Outcomes

• Well-documented and consistent API designs

Related metrolines

• API Design Line

Why it matters

Designing APIs is not just about naming endpoints. Good design ensures APIs are usable, consistent, and aligned with business and technical goals. Poorly designed APIs result in technical debt, poor adoption, and rework across teams.

Entry criteria

• The API architecture uses patterns that promote reusability and integration, and is validated with stakeholders.
• The goal of the API is to hide backend data models and discrepancies.
• The API’s design and endpoints have a clear connection to their business value and features.
• API has a consistent design with our other API products.

Exit criteria

• The API architecture uses patterns that promote reusability and integration, and is validated with stakeholders.
• The goal of the API is to hide backend data models and discrepancies.
• The API’s design and endpoints have a clear connection to their business value and features.
• API has a consistent design with our other API products.

How it works

1. Define core entities, their attributes, and relationships to create a shared conceptual understanding across APIs.
   Domain Canvas A modeling tool to define and communicate the key entities and relationships in your domain, ensuring semantic consistency across APIs.
2. Use the Interaction Canvas to define how consumers will interact with the API, ensuring it meets their needs and expectations.
   Interaction Canvas Define API interactions, workflows, and expected responses to ensure a consistent API consumer experience.
3. Apply REST design patterns to create consistent, reusable API contracts that are validated with stakeholders.
   REST Canvas Design APIs using RESTful principles, defining resources, verbs, and example requests and responses.
4. Apply Event-driven design patterns to create consistent, reusable API contracts that are validated with stakeholders.
   Event Canvas Design event-driven APIs by defining events, triggers, and processing logic.
5. Apply GraphQL design patterns to create consistent, reusable API contracts that are validated with stakeholders.
   GraphQL Canvas Design GraphQL APIs by defining types, queries, mutations, and subscriptions.
6. Use insights to design APIs that meet consumer needs, ensuring they are discoverable, understandable, and usable.
   API Design Principles A concise guide to API usability, discoverability, and consistency grounded in proven design philosophies and user needs.
7. Use the API Audit Checklist to ensure the API design meets functional and non-functional requirements, including security, performance, and compliance.
   API Audit Checklist A comprehensive checklist to verify API readiness before publishing, covering design, documentation, security, and policy compliance.

Apply in your work

Provide reusable templates, standards, and validation tools for API specifications. Ensure teams follow design reviews and incorporate feedback early.