# Solution & Interface Design

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

Language: en

Entity ID: api-design

## Description

Design the integration solution, contracts, schemas, data structures, mappings, and interaction or delivery patterns for the selected style.

## Why it matters

Once the architecture pattern is known, the design must turn capability requirements into clear interface contracts, interactions, schemas, data rules, lifecycle expectations, and consumer obligations.

## Apply in work

Select the design resources that fit the chosen implementation style and document the interface contract before implementation.

## Outcomes

- A validated interface contract for the selected implementation style
- Consistent interaction, data, event, file, workflow, or API contract decisions
- Design traceability back to capability and consumer requirements
- Designs aligned with domain models and interaction patterns

## Steps

1. Start from the selected architecture decision and use the Interaction Canvas or style-specific design guide as the primary design path.
2. Confirm domain concepts, ownership, data rules, and mappings before contract design.
3. Choose only the relevant style-specific design artifacts for REST, GraphQL, event, messaging, file, stream, data product, direct integration, connector, or hybrid implementation.
4. Apply contract-first integration design using OpenAPI, AsyncAPI, event schemas, message schemas, file schemas, data contracts, or interface specifications where useful.
5. Define examples, lifecycle rules, compatibility expectations, consumer obligations, and validation evidence.
6. Keep REST, Event, and GraphQL canvases conditional when those styles are selected.
7. Add file, stream, data product, queue, or direct-integration design support when those styles are selected.
8. Trace design decisions back to consumer/provider requirements and the architecture decision.

## Questions

- Start from the selected architecture decision and use the Interaction Canvas or style-specific design guide as the primary design path.
- Confirm domain concepts, ownership, data rules, and mappings before contract design.
- Choose only the relevant style-specific design artifacts for REST, GraphQL, event, messaging, file, stream, data product, direct integration, connector, or hybrid implementation.
- Apply contract-first integration design using OpenAPI, AsyncAPI, event schemas, message schemas, file schemas, data contracts, or interface specifications where useful.
- Define examples, lifecycle rules, compatibility expectations, consumer obligations, and validation evidence.
- Keep REST, Event, and GraphQL canvases conditional when those styles are selected.
- Add file, stream, data product, queue, or direct-integration design support when those styles are selected.
- Trace design decisions back to consumer/provider requirements and the architecture decision.
- Select the design resources that fit the chosen implementation style and document the interface contract before implementation.
- Once the architecture pattern is known, the design must turn capability requirements into clear interface contracts, interactions, schemas, data rules, lifecycle expectations, and consumer obligations.

## Evidence

- spec
- contract
- design-artifact
- documentation

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

## 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.; suggested-answer-owner: [Capability Solution Design Canvas](https://apiopscycles.com/resources/capability-solution-design-canvas.md)
- [Automation Engineer](https://apiopscycles.com/roles/automation-engineer.md) (lead): Implements, tests, integrates, and maintains automation solutions and supporting workflows.; suggested-answer-owner: [Automation Workflow Canvas](https://apiopscycles.com/resources/automation-workflow-canvas.md)
- [Integration Architect](https://apiopscycles.com/roles/integration-architect.md) (lead): Designs integration approaches and implementation styles that connect the capability or API with other systems.; suggested-answer-owner: [Integration Solution Design Canvas](https://apiopscycles.com/resources/integration-solution-design-canvas.md)
- [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.
- [Automation Owner](https://apiopscycles.com/roles/automation-owner.md) (core): Owns automation goals, business value, priorities, controls, and lifecycle outcomes.
- [Capability Owner](https://apiopscycles.com/roles/capability-owner.md) (core): Owns the capability vision, value, priorities, lifecycle, and reuse across consumers.
- [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.
- [Platform Architect](https://apiopscycles.com/roles/platform-architect.md) (core): Guides platform, integration, scalability, and architecture decisions that shape how the capability or API is built and operated.
- [Process Owner](https://apiopscycles.com/roles/process-owner.md) (core): Owns the business process being automated, including objectives, rules, outcomes, and improvement priorities.
- [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.

## Cycle-specific guidance

- [Capability Productization Cycle](https://apiopscycles.com/cycles/capability-productization-cycle/stations/api-design.md)
- [API Productization Cycle](https://apiopscycles.com/cycles/api-productization-cycle/stations/api-design.md)
- [Integration Productization Cycle](https://apiopscycles.com/cycles/integration-productization-cycle/stations/api-design.md)
- [Automation Cycle](https://apiopscycles.com/cycles/automation-cycle/stations/api-design.md)