Как будешь описывать API-запрос в формате REST?

Документирование REST API запросов: Best Practices для Business Analyst

Введение

Business Analyst нужно уметь описывать API запросы так, чтобы это было понятно и разработчикам, и другим stakeholders. За 10+ лет я выработал систематический подход к этому.

Основной формат описания

Я использую комбинацию нескольких подходов в зависимости от контекста:

1. Простой текстовой формат для документации

Для вики и документов я использую этот формат:

### Endpoint: Get User Profile

**HTTP Method:** GET
**URL:** /api/v1/users/{user_id}
**Authentication:** Bearer Token required

#### Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| user_id | UUID | Unique identifier of the user |

#### Query Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| include | string | No | Comma-separated fields to include (profile, settings) |
| format | string | No | Response format (json, xml). Default: json |

#### Response (200 OK)
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "john@example.com",
  "name": "John Doe",
  "created_at": "2024-01-15T10:30:00Z",
  "subscription": {
    "status": "active",
    "plan": "premium",
    "expires_at": "2025-01-15"
  }
}

#### Response Codes
- **200 OK**: User found and returned
- **401 Unauthorized**: Invalid or missing authentication token
- **404 Not Found**: User not found
- **429 Too Many Requests**: Rate limit exceeded

#### Example cURL
curl -X GET "https://api.example.com/api/v1/users/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

2. OpenAPI/Swagger спецификация (для интеграций)

Когда нужна техническая точность и автоматизация, я использую OpenAPI 3.0:

openapi: 3.0.0
info:
  title: Subscription Management API
  version: 1.0.0

paths:
  /api/v1/subscriptions:
    post:
      summary: Create new subscription
      tags:
        - Subscriptions
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  format: uuid
                  description: User ID
                plan_id:
                  type: string
                  enum: [starter, professional, enterprise]
                  description: Subscription plan
                auto_renew:
                  type: boolean
                  default: true
                  description: Enable automatic renewal
              required:
                - user_id
                - plan_id
      responses:
        201:
          description: Subscription created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  user_id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum: [active, cancelled, expired]
                  created_at:
                    type: string
                    format: date-time
        400:
          description: Invalid input
        409:
          description: User already has active subscription

3. Postman Collection (для тестирования)

Я создаю и документирую Postman collections, которые становятся executable specification:

{
  "info": {
    "name": "Payment Integration API",
    "description": "API для обработки платежей",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/"
  },
  "item": [
    {
      "name": "Process Payment",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Authorization",
            "value": "Bearer {{auth_token}}"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{request_id}}",
            "description": "Unique request ID for idempotency"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  "user_id": "{{user_id}}",\n  "amount": 29.99,\n  "currency": "USD",\n  "payment_method_id": "pm_123abc",\n  "description": "Monthly subscription",\n  "metadata": {\n    "order_id": "ORD-12345",\n    "source": "web"\n  }\n}"
        },
        "url": {
          "raw": "{{base_url}}/api/v1/payments",
          "protocol": "https",
          "host": ["api", "example", "com"],
          "path": ["api", "v1", "payments"]
        }
      },
      "response": [
        {
          "name": "Success Response",
          "status": "Created",
          "code": 201,
          "body": "{\n  "id": "pay_123abc",\n  "status": "completed",\n  "amount": 29.99,\n  "currency": "USD",\n  "created_at": "2024-03-26T15:30:00Z"\n}"
        },
        {
          "name": "Duplicate Request",
          "status": "OK",
          "code": 200,
          "body": "{\n  "id": "pay_123abc",\n  "status": "completed",\n  "note": "Duplicate request detected, returning previous result"\n}"
        }
      ]
    }
  ]
}

4. User Story формат с API интеграцией

Когда описываю требование в User Story, включаю API детали:

### User Story: Customer can view transaction history

**As a** paying customer
**I want to** view my transaction history
**So that** I can track my spending and subscriptions

#### API Integration
**Endpoint:** GET /api/v1/customers/{customer_id}/transactions

**Query Parameters:**
- limit: 20 (default)
- offset: 0 (default)
- from_date: ISO 8601 date (optional)
- to_date: ISO 8601 date (optional)
- status: comma-separated (pending,completed,failed) (optional)

**Expected Response:**
```json
{
  "total": 150,
  "limit": 20,
  "offset": 0,
  "items": [

{
  "id": "txn_abc123",
  "amount": 29.99,
  "currency": "USD",
  "status": "completed",
  "type": "subscription_payment",
  "created_at": "2024-03-26T10:15:00Z",
  "description": "Monthly Pro subscription"
}

  ]

}

Acceptance Criteria:

• Page loads with user's last 20 transactions
• User can filter by date range (from/to)
• User can filter by transaction status
• Pagination works correctly (next/previous)
• API response time < 200ms
• Handles empty transaction list gracefully
• Currency symbol matches user's locale

### 5. Таблица API методов (для обзора)

Когда нужна высокоуровневый обзор, я создаю таблицу:

| Method | Endpoint | Purpose | Auth | Rate Limit | Notes |
|--------|----------|---------|------|-----------|-------|
| GET | /api/v1/users/{id} | Retrieve user profile | Required | 100/min | Public data only |
| POST | /api/v1/users | Create new user | API Key | 10/min | Email validation required |
| PUT | /api/v1/users/{id} | Update user profile | Required | 100/min | Only user's own data |
| DELETE | /api/v1/users/{id} | Delete user account | Required | 5/min | Irreversible, triggers audit log |
| GET | /api/v1/subscriptions | List user subscriptions | Required | 100/min | Includes cancelled |
| POST | /api/v1/subscriptions | Create subscription | Required | 20/min | Auto-renew default enabled |

### 6. Диаграмма sequence для сложных потоков

Когда API запросы взаимозависимы, использую sequence диаграммы:

Клиент → API: POST /api/v1/payments (Create payment) API → Payment Service: Process payment Payment Service → Bank: Request transaction Bank → Payment Service: Approve/Decline Payment Service → Webhook: Send status update Webhook → Клиент: payment.completed event Клиент → API: GET /api/v1/payments/{id} (Confirm status)

### Правила, которые я применяю

**1. RESTful соглашения**
- GET для чтения
- POST для создания
- PUT/PATCH для обновления
- DELETE для удаления
- Статус коды: 200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 409 (Conflict), 429 (Rate Limit), 500 (Server Error)

**2. Версионирование**
- Всегда в URL: /api/v1/ (не в header)
- Позволяет поддерживать backward compatibility

**3. Именование**
- Существительные, не глаголы: /api/v1/users (не /api/v1/getUsers)
- Множественное число для коллекций: /api/v1/users
- Единственное число для операций: /api/v1/users/{id}/profile

**4. Обязательные детали**
- **Method**: HTTP глагол (GET, POST, etc)
- **URL**: Полный path с параметрами
- **Auth**: Требуется ли, какой тип
- **Request Body**: Структура, типы данных, обязательные поля
- **Response Codes**: Все возможные, с описанием
- **Response Body**: Примеры для каждого статус кода
- **Rate Limits**: Если есть
- **Pagination**: Если applicable

**5. Примеры с реальными данными**
- Не использую placeholder'ы вроде "data"
- Дам реальные примеры: order IDs, email адреса
- Включу edge cases: empty list, error response

### Где я это документирую

**Разработчикам → OpenAPI + Postman:**
- Наиболее точно, executable
- Интегрируется с API тестированием
- Автогенерирует документацию

**Product Manager → User Stories + таблицы:**
- Понятен business контекст
- Связан с требованиями
- Трассируемость

**Клиентам (external partners) → Confluence + Postman:**
- Красивая документация
- Примеры с curl/Python/JavaScript
- Playground для тестирования

**Аудит/Compliance → Детальные спецификации:**
- Все возможные параметры
- Security требования
- Rate limiting rules

### Итоговый чеклист при документировании API

- [ ] HTTP Method определён (GET/POST/PUT/DELETE/PATCH)
- [ ] URL path ясна, с примерами параметров
- [ ] Authentication тип описан
- [ ] Все path параметры задокументированы
- [ ] Все query параметры задокументированы
- [ ] Request body описан со примером
- [ ] Response успешного запроса показан
- [ ] Все возможные status codes перечислены
- [ ] Response структура типизирована (JSON Schema)
- [ ] Примеры cURL или SDK приложены
- [ ] Rate limits указаны (если есть)
- [ ] Pagination задокументирована (если есть)
- [ ] Error scenarios описаны
- [ ] Дата последнего обновления указана
- [ ] Version истории/changelog включен

REST API документирование — это баланс между точностью и доступностью. Я стараюсь делать её достаточно точной для разработчиков, но достаточно понятной для остальных stakeholders.