# patterns-api-contracts

> This skill MUST be invoked when the user says "design API", "map endpoints", "define schemas", "API contract", "REST API design", or "OpenAPI spec". SHOULD also invoke when user mentions "endpoint", "schema", "contract", or "HTTP".

- Author: deepeshBodh
- Repository: deepeshBodh/human-in-loop-marketplace
- Version: 20260206155937
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/deepeshBodh/human-in-loop-marketplace
- Web: https://mule.run/skillshub/@@deepeshBodh/human-in-loop-marketplace~patterns-api-contracts:20260206155937

---

---
name: patterns-api-contracts
description: This skill MUST be invoked when the user says "design API", "map endpoints", "define schemas", "API contract", "REST API design", or "OpenAPI spec". SHOULD also invoke when user mentions "endpoint", "schema", "contract", or "HTTP".
---

# Designing API Contracts

## Overview

Design RESTful API contracts that map user actions to endpoints with complete schema definitions and comprehensive error handling. Every user action becomes an endpoint; every endpoint has request/response schemas and error handling.

## When to Use

- Designing new API endpoints for a feature
- Mapping user actions to HTTP methods and paths
- Creating OpenAPI specifications from requirements
- Defining request/response schemas for endpoints
- Documenting error responses for an API
- Integrating with existing API patterns (brownfield)
- Creating contracts/ directory artifacts

## When NOT to Use

- **GraphQL API design** - Different paradigm, not RESTful
- **WebSocket or real-time streaming** - Use specialized patterns
- **Internal microservice communication** - When external contracts aren't needed
- **Entity modeling** - Use `humaninloop:patterns-entity-modeling` first
- **Technical architecture decisions** - Use `humaninloop:patterns-technical-decisions`

## Endpoint Mapping

### User Action to Endpoint Mapping

| User Action | HTTP Method | Endpoint Pattern |
|-------------|-------------|------------------|
| Create resource | POST | `/resources` |
| List resources | GET | `/resources` |
| Get single resource | GET | `/resources/{id}` |
| Update resource | PUT/PATCH | `/resources/{id}` |
| Delete resource | DELETE | `/resources/{id}` |
| Perform action | POST | `/resources/{id}/{action}` |
| Get nested resource | GET | `/resources/{id}/children` |

### Method Selection

| Scenario | Method | Idempotent? |
|----------|--------|-------------|
| Create new resource | POST | No |
| Full replacement | PUT | Yes |
| Partial update | PATCH | No |
| Read resource | GET | Yes |
| Remove resource | DELETE | Yes |
| Trigger action | POST | Usually No |

### Resource Naming Conventions

- Use plural nouns: `/users`, not `/user`
- Use kebab-case for multi-word: `/user-profiles`
- Use path params for IDs: `/users/{userId}`
- Use query params for filtering: `/users?role=admin`
- Use nested paths for relationships: `/users/{userId}/tasks`

## Endpoint Documentation Format

Document each endpoint with description, source requirements, request/response schemas, and error cases:

```markdown
## POST /api/auth/login

**Description**: Authenticate user with email and password

**Source Requirements**: FR-001, US#1

### Request
{JSON request body example}

### Response (200 OK)
{JSON response body example}

### Error Responses
| Status | Code | Description |
|--------|------|-------------|
| 400 | INVALID_INPUT | Missing or malformed fields |
| 401 | INVALID_CREDENTIALS | Wrong email or password |
```

## Schema Definition

### Request Schema Format

```yaml
LoginRequest:
  type: object
  required:
    - email
    - password
  properties:
    email:
      type: string
      format: email
      description: User's email address
    password:
      type: string
      minLength: 8
      description: User's password
```

### Type Mapping from Data Model

| Data Model Type | OpenAPI Type | Format |
|-----------------|--------------|--------|
| UUID | string | uuid |
| Text | string | - |
| Email | string | email |
| URL | string | uri |
| Integer | integer | int32/int64 |
| Decimal | number | float/double |
| Boolean | boolean | - |
| Timestamp | string | date-time |
| Date | string | date |
| Enum[a,b,c] | string | enum: [a,b,c] |

## Error Response Design

Use standard error format with machine-readable codes and human-readable messages.

See [ERROR-PATTERNS.md](references/ERROR-PATTERNS.md) for complete HTTP status codes, error code conventions, and response formats.

### Quick Reference

| Status | When to Use |
|--------|-------------|
| 400 | Invalid input format |
| 401 | Missing/invalid auth |
| 403 | No permission |
| 404 | Resource missing |
| 409 | State conflict |
| 422 | Business rule violation |
| 429 | Rate limit exceeded |
| 500 | Server error |

## List Endpoints

For endpoints returning collections, implement pagination, filtering, and sorting.

See [PAGINATION-PATTERNS.md](references/PAGINATION-PATTERNS.md) for offset vs cursor pagination, filtering operators, and sorting patterns.

### Quick Reference

```
GET /api/users?page=1&limit=20&role=admin&sort=-createdAt
```

## Brownfield Considerations

When existing API patterns are detected, align new endpoints:

| Aspect | Check For |
|--------|-----------|
| Base path | `/api/v1`, `/api`, etc. |
| Auth pattern | Bearer, API key, session |
| Error format | Existing error structure |
| Pagination | page/limit, cursor, offset |

Handle endpoint collisions:
- REUSE existing endpoints when possible
- RENAME to match existing patterns
- NEW only when no existing endpoint fits

## OpenAPI Structure

See [OPENAPI-TEMPLATE.yaml](references/OPENAPI-TEMPLATE.yaml) for a complete, copy-ready template with all sections.

### Minimal Structure

```yaml
openapi: 3.0.3
info:
  title: {Feature Name} API
  version: 1.0.0

servers:
  - url: /api

paths:
  /resource:
    get: ...
    post: ...

components:
  schemas: ...
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

security:
  - bearerAuth: []
```

## Traceability

Track endpoint to requirement mapping:

| Endpoint | Method | FR | US | Description |
|----------|--------|-----|-----|-------------|
| /auth/login | POST | FR-001 | US#1 | User login |
| /users/me | GET | FR-004 | US#4 | Get current user |

## Validation

Validate OpenAPI specifications using the validation script:

```bash
python scripts/validate-openapi.py path/to/openapi.yaml
```

Checks: OpenAPI syntax, REST conventions, error responses, request bodies, operation IDs, security schemes, examples, and descriptions.

## Quality Checklist

Before finalizing API contracts:

- [ ] Every user action has an endpoint
- [ ] All endpoints have request schema (if applicable)
- [ ] All endpoints have success response schema
- [ ] All endpoints have error responses defined
- [ ] Naming follows REST conventions
- [ ] Authentication requirements documented
- [ ] Brownfield patterns matched (if applicable)
- [ ] OpenAPI spec is valid
- [ ] Traceability to requirements complete

## Common Mistakes

### Verbs in URLs
❌ `/getUsers`, `/createUser`, `/deleteUser`
✅ `/users` with appropriate HTTP methods (GET, POST, DELETE)

### GET for State-Changing Actions
❌ `GET /users/{id}/delete`
✅ `DELETE /users/{id}` or `POST /users/{id}/archive`

### Missing Error Responses
❌ Only documenting 200 OK response
✅ Define all error cases: 400, 401, 403, 404, 409, 422, 500

### Inconsistent Naming
❌ Mixing `/user-profiles`, `/userSettings`, `/user_preferences`
✅ Pick one style consistently: `/user-profiles`, `/user-settings`, `/user-preferences`

### Generic Error Codes
❌ Just returning 400 or 500 for all errors
✅ Specific codes: `INVALID_EMAIL`, `USER_NOT_FOUND`, `RATE_LIMIT_EXCEEDED`

### Missing Examples
❌ Schema definitions without realistic example values
✅ Include `example:` fields showing real-world data

### Skipping Brownfield Check
❌ Creating new patterns when existing API conventions exist
✅ Always check existing API style (auth, error format, pagination) first