Station

API Design

Create API designs that are consistent, reusable, and grounded in business intent and shared standards.

Designing APIs is not just about naming endpoints. Good design ensures APIs are usable, consistent, and aligned with business and technical goals. Poor design leads to tight coupling, low reuse, and costly rework across teams.

Method map

Metro map

Select a cycle, station, or stakeholder to open its permanent method page.

StrategicGovernanceConsumerTechnicalUser ExperienceUser ExperienceMarket InsightsMarket InsightsBusiness GoalsBusiness GoalsCompetitive AnalysisCompetitive AnalysisEcosystem VisionEcosystem VisionScalable InfrastructureScalable InfrastructureLegal and ComplianceLegal and ComplianceSecurity and PrivacySecurity and PrivacyDesign StandardsDesign StandardsVendor ManagementVendor ManagementContract DesignContract DesignDevelopmentDevelopmentCI/CDCI/CDTest AutomationTest AutomationRelease ManagementRelease ManagementService AgreementsService AgreementsConsumer AdoptionConsumer AdoptionPromotionPromotionPartner IntegrationPartner IntegrationAPI MindsetAPI MindsetRoles and ResponsibilitiesRoles and ResponsibilitiesUpskillingUpskillingOperating GuidelinesOperating GuidelinesPortfolio ManagementPortfolio ManagementBudget and Resource ManagementBudget and Resource ManagementStrategy1API Product StrategyConsumer Requirements & Onboarding2API Consumer ExperienceArchitecture & Platform Decisions3API PlatformArchitectureSolution & Interface Design4API DesignDelivery & Operations5API DeliveryQuality & Readiness Assurance6API AuditPublishing & Enablement7API PublishingMonitoring & Improvement8API Monitoring &ImprovementBusiness Opportunities LinePlatform Architecture LineDesign LineDelivery LinePublishing and Adoption LineOperating Model Line

Selected station: Solution & Interface Design

People to involve

Related resources

Outcomes

  • Well-documented and consistent API designs
  • Reusable and validated API contracts
  • Designs aligned with domain models and interaction patterns
  • Design traceability to business value

Journey criteria

Entry criteria

  • The capability addresses a clear business need and is reusable by its intended consumers.
  • The selected interface provides an appropriate abstraction for consumers.
  • The capability value proposition has been validated with business and consumer stakeholders.
  • Consumer segments are identified.
  • A high-level implementation roadmap is defined.

Exit criteria

  • The chosen architecture, platform, and implementation style have been validated with the relevant architecture, security, and platform stakeholders.
  • The selected interface provides an appropriate abstraction for consumers.
  • The interface design and exposed capabilities trace back to business value and consumer needs.
  • The interface design follows agreed design standards and conventions.

This is what success looks like

Provide reusable design patterns, shared standards, and validation tools for API specifications. Ensure design decisions are consistent, reviewed early, and aligned with business intent.

  1. Define core entities, their attributes, and relationships to create a shared conceptual understanding across APIs. — Domain Canvas
  2. Use the Interaction Canvas to define how consumers will interact with the API, ensuring it meets their needs and expectations. — Interaction Canvas
  3. Apply REST design patterns to create consistent, reusable API contracts that are validated with stakeholders. — REST Canvas
  4. Apply Event-driven design patterns to create consistent, reusable API contracts that are validated with stakeholders. — Event Canvas
  5. Apply GraphQL design patterns to create consistent, reusable API contracts that are validated with stakeholders.
  6. Use the design principles and API style guide to align your design decisions with shared rules and enable consistent audit validation. — API Design Principles
  7. Apply contract-first or design-first approaches to capture and validate the API contract before implementation.
  8. Use the API Audit Checklist to ensure the API design meets functional and non-functional requirements, including security, performance, and compliance. — API Audit Checklist

Metro lines

Design Line

Focuses on solution and interface design principles that can be used across APIs, integrations, automations, data products, and other implementation styles.

Review station resources

Browse the resources selected for API Design; the summary above explains how they support this station’s work.

Station resources

Resources for API Design

canvas

Interaction Canvas

Define interactions, workflows, inputs, outputs, commands, queries, events, and expected responses to ensure a consistent consumer experience.

Outcomes

  • Defined interaction model for the selected capability
  • Inputs, outputs, commands, queries, events, and responses clarified
  • Validation rules and interaction expectations agreed

How it works

  1. Map interactions to user, consumer, or system tasks
  2. Define access points, operations, commands, queries, or events for each interaction
  3. Document inputs and outputs for each interaction.
  4. Specify validation rules and constraints
  5. Create interaction models for CRUD, query-driven, command-driven, and event-driven interactions

Relevant cycles

API Productization Cycle

The API-focused APIOps Cycles journey for productizing, designing, delivering, publishing, and improving APIs.

Automation Cycle

A cycle for identifying, designing, delivering, enabling, and improving automation opportunities.