# API Documentation

> Document RESTful APIs and integration requirements for developers and external partners

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

---


# API Documentation Skill

## Purpose
Define integration requirements and document API specifications to ensure smooth communication between systems (e.g., Frontend to Backend, or Service to Service).

## When to Use
- Designing new API endpoints (e.g., FRS for Backend).
- Integrating with 3rd party services (e.g., Stripe, SendGrid).
- Documenting public APIs for partners.
- Defining payload structures for developers.

## Key API Concepts for BAs

### 1. Protocols
- **REST (Representational State Transfer)**: Most common. Resource-based.
- **SOAP**: Older, XML-based. Heavy enterprise use.
- **GraphQL**: Flexible, query-based. Client asks for exactly what it needs.

### 2. HTTP Methods (Verbs)
- **GET**: Retrieve data (Read).
- **POST**: Create new data (Create).
- **PUT**: Update/Replace full data (Update).
- **PATCH**: Update partial data (Update).
- **DELETE**: Remove data (Delete).

### 3. Status Codes
- **200 OK**: Success.
- **201 Created**: Success (new resource made).
- **400 Bad Request**: Client error (invalid input).
- **401 Unauthorized**: Authentication missing/failed.
- **403 Forbidden**: Authentication passed, but permission denied.
- **404 Not Found**: Resource doesn't exist.
- **500 Internal Server Error**: Backend crashed.

## Documentation Structure (Swagger/OpenAPI Style)

### Required Sections per Endpoint

1. **Title & Method**: `GET /api/v1/users/{userId}`
2. **Summary**: One-line description of what it does.
3. **Parameters**:
   - **Path Params**: Required ID in URL (e.g., `{userId}`).
   - **Query Params**: Filter/Sort limits (e.g., `?limit=10&role=admin`).
   - **Body**: JSON payload (for POST/PUT).
   - **Headers**: Auth tokens, Content-Type.
4. **Response Examples**:
   - Success (200) JSON body.
   - Error (4xx/5xx) JSON body.
5. **Business Rules**: Constraints, logic, side effects.

## API Specification Template (Simple)

### Endpoint: Create New Order

**Method**: `POST`
**URL**: `/api/v1/orders`
**Description**: Creates a new customer order and reserves inventory.

**Request Headers**:
- `Authorization`: Bearer `<token>`
- `Content-Type`: `application/json`

**Request Body (JSON)**:
```json
{
  "customerId": "uuid-string",
  "items": [
    {
      "productId": "uuid-string",
      "quantity": 2
    }
  ],
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Startown"
  }
}
```

**Constraints**:
- `quantity` must be > 0.
- `customerId` must be active.
- Max 20 items per order.

**Success Response (201 Created)**:
```json
{
  "orderId": "ord-12345",
  "status": "PENDING",
  "totalAmount": 150.00,
  "createdAt": "2026-01-21T10:00:00Z"
}
```

**Error Responses**:
- **400 Bad Request**: "Invalid Quantity" or "Product Out of Stock".
- **401 Unauthorized**: Token expired.

## Mapping Integrations (Data Mapping)

When connecting System A to System B, create a Mapping Table:

| Source Field (System A) | Type | Transformation | Destination Field (System B) | Type | Notes |
|-------------------------|------|----------------|------------------------------|------|-------|
| `first_name` | Str | Concat | `FullName` | Str | A.first + " " + A.last |
| `last_name` | Str | (above) | - | - | |
| `dob` | Date | Format `YYYY-MM-DD` | `BirthDate` | Str | B requires string format |
| `status` | Enum | Map 'Active'->1 | `IsActive` | Bool | Logic mapping |

## Tools
- **Swagger / OpenAPI**: Standard for dev docs.
- **Postman**: Testing API calls.
- **Stoplight**: Visual API design.
- **Lark Docs / Markdown**: Writing specs for BRD/FRS.

## Best Practices
- **Be Consistent**: Use ISO 8601 for dates (`YYYY-MM-DDThh:mm:ssZ`).
- **Authentication**: Explicitly state how auth works (API Key vs OAuth).
- **Pagination**: Don't return 1 million records. Specify default limits (`limit=20`).
- **Error Messages**: Define clear human-readable error messages.

## Reference
- RESTful API Design Guide.
- OpenAPI Specification (OAS).