# API Design

> API-First design patterns, user stories, and sequence diagrams. Trigger: When designing APIs with OpenAPI, user stories, or sequence diagrams.

- Skill: `odjaramillo/api-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add odjaramillo/api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/odjaramillo/api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: Apache-2.0
- Author: odjaramillo (https://skillmd.com/u/odjaramillo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/odjaramillo/api-design

---


## Critical Patterns

### API-First Approach (REQUIRED)

```
Design the API (OpenAPI Spec) BEFORE writing code or user stories.
Protocol: Assume HTTP RESTful by default unless specified (gRPC, EDA).
```

### User Story Format (REQUIRED)

```
As [user role],
I want [specific objective],
So that [benefit and/or value].
```

### Acceptance Criteria (REQUIRED)

```gherkin
Scenario: [Scenario Name]
  Given [pre-condition]
  When [action]
  Then [expected result]
```

---

## Decision Tree

```
Need API design?           → Start with OpenAPI spec
Need user story?           → Use As/I want/So that format
Need test cases?           → Use Gherkin Given/When/Then
Need flow visualization?   → Use Mermaid sequenceDiagram
```

---

## Code Examples

### OpenAPI Endpoint

```yaml
paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
```

### Sequence Diagram

```mermaid
sequenceDiagram
    Client->>API: POST /orders
    API->>Service: validateOrder()
    Service->>Database: INSERT order
    Database-->>Service: orderId
    Service-->>API: Order created
    API-->>Client: 201 Created
```

### User Story Example

```
As an authenticated user,
I want to view my order history,
So that I can track my past purchases.

Acceptance Criteria:
Scenario: View order history
  Given I am logged in
  When I navigate to /orders
  Then I see a list of my orders sorted by date
  And each order shows status and total amount
```

---

## Success Metrics

- **Business**: ROI, user adoption
- **Performance**: Latency, throughput
- **Infrastructure**: Error rates, uptime
- **SLIs/SLOs**: Specific service level objectives