# API Design — API Productization Cycle

Canonical page: https://apiopscycles.com/cycles/api-productization-cycle/stations/api-design

Language: en

Entity ID: api-design

Cycle: [API Productization Cycle](https://apiopscycles.com/cycles/api-productization-cycle.md)

Read [shared station guidance](https://apiopscycles.com/stations/api-design.md) first. The sections below supplement or replace the corresponding shared sections for this cycle. Sections not repeated here retain the shared guidance.

## Journey entry criteria

- The capability addresses a clear business need and is reusable by its intended consumers. — The API meets a clear business need and is reusable for multiple API consumers. (ID: api-reusability)
- The selected interface provides an appropriate abstraction for consumers. — The API is intended to shield consumers from backend complexity and inconsistencies. (ID: hide-backend-discrepancies)
- The capability value proposition has been validated with business and consumer stakeholders. — The API value proposition has been reviewed and validated with the relevant business and consumer stakeholders. (ID: value-prop-validated)
- Consumer segments are identified. — API consumer segments (internal and external) are identified. (ID: consumer-segments-identified)
- A high-level implementation roadmap is defined. — High-level roadmaps for API development are established. (ID: api-roadmap-defined)

## Journey exit criteria

- The chosen architecture, platform, and implementation style have been validated with the relevant architecture, security, and platform stakeholders. — The chosen API architecture and platform patterns have been validated with the relevant architecture, security, and platform stakeholders. (ID: architecture-patterns-validated)
- The selected interface provides an appropriate abstraction for consumers. — The API is intended to shield consumers from backend complexity and inconsistencies. (ID: hide-backend-discrepancies)
- The interface design and exposed capabilities trace back to business value and consumer needs. — The API design and exposed capabilities clearly trace back to business value and user needs. (ID: design-reflects-business-value)
- The interface design follows agreed design standards and conventions. — The API design follows our shared API product and design conventions. (ID: api-consistency)

## Description

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

## 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. Poor design leads to tight coupling, low reuse, and costly rework across teams.

## Apply in work

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

## 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

## Steps

1. Define core entities, their attributes, and relationships to create a shared conceptual understanding across APIs.
2. Use the Interaction Canvas to define how consumers will interact with the API, ensuring it meets their needs and expectations.
3. Apply REST design patterns to create consistent, reusable API contracts that are validated with stakeholders.
4. Apply Event-driven design patterns to create consistent, reusable API contracts that are validated with stakeholders.
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.
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.

## Questions

- Define core entities, their attributes, and relationships to create a shared conceptual understanding across APIs.
- Use the Interaction Canvas to define how consumers will interact with the API, ensuring it meets their needs and expectations.
- Apply REST design patterns to create consistent, reusable API contracts that are validated with stakeholders.
- Apply Event-driven design patterns to create consistent, reusable API contracts that are validated with stakeholders.
- Apply GraphQL design patterns to create consistent, reusable API contracts that are validated with stakeholders.
- Use the design principles and API style guide to align your design decisions with shared rules and enable consistent audit validation.
- Apply contract-first or design-first approaches to capture and validate the API contract before implementation.
- Use the API Audit Checklist to ensure the API design meets functional and non-functional requirements, including security, performance, and compliance.
- Provide reusable design patterns, shared standards, and validation tools for API specifications. Ensure design decisions are consistent, reviewed early, and aligned with business intent.
- 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.

## Role participation and responsibilities

- [API Designer](https://apiopscycles.com/roles/api-designer.md) (lead): Shapes the interface contract, interaction model, consistency, and usability of the exposed capabilities.
- [API Consumer Representative](https://apiopscycles.com/roles/api-consumer-specialist.md) (core): Represents the needs of developers, integrators, or other API consumers who use the API directly.
- [API Product Owner](https://apiopscycles.com/roles/api-product-owner.md) (core): Drives the API opportunity, prioritization, and product-level decisions across the lifecycle.
- [Compliance and Legal Specialist](https://apiopscycles.com/roles/compliance-specialist.md) (core): Clarifies legal, privacy, regulatory, and contractual requirements that affect the capability, API, interface, or automation.
- [Domain Expert](https://apiopscycles.com/roles/domain-specialist.md) (core): Brings deep knowledge of the business domain, concepts, rules, and constraints the capability or interface must reflect.
- [Security Specialist](https://apiopscycles.com/roles/security-specialist.md) (core): Ensures security risks, controls, and trust boundaries are addressed throughout the API lifecycle.
- [Business Owner](https://apiopscycles.com/roles/business-owner.md) (consulted): Represents business goals, funding, and expected outcomes for the capability, API, or automation initiative.
- [Delivery Engineer](https://apiopscycles.com/roles/api-engineer.md) (consulted): Owns implementation, automation, testing, and release flow concerns needed to deliver the capability, API, or automation reliably.
- [Documentation and DevRel Owner](https://apiopscycles.com/roles/api-devrel-specialist.md) (consulted): Owns onboarding content, developer communication, and documentation quality for API consumers.
- [Platform Architect](https://apiopscycles.com/roles/platform-architect.md) (consulted): Guides platform, integration, scalability, and architecture decisions that shape how the capability or API is built and operated.

## Resources

- [Interaction Canvas](https://apiopscycles.com/resources/interaction-canvas.md)
- [REST Canvas](https://apiopscycles.com/resources/rest-canvas.md)
- [Event Canvas](https://apiopscycles.com/resources/event-canvas.md)
- [API Design Principles](https://apiopscycles.com/resources/api-design-principles.md)
- [Domain Canvas](https://apiopscycles.com/resources/domain-canvas.md)