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)

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

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

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