Чи безкоштовна ця стаття?

Так. Усі статті на CoderSlingo, включно з цією, доступні безкоштовно без реєстрації.

Коли опубліковано цю статтю?

Цю статтю опубліковано у 2026 році.

Писання документації API англійською мовою: шаблони і приклади

Q: Про що ця стаття "Писання документації API англійською мовою: шаблони і приклади"?

Як написати чітку, професійну документацію API англійською мовою. Шаблони для кінцевих точок, параметрів, кодів помилок і підручників з SDK — з реальними прикладами.

Документацію API читають тисячі розробників. Це один з найважливіших елементів технічного письма, який розробник буде виробляти — і один з найменш вивчених. Погано задокументований API розчарує інтеграторів, генерує нескінченні квитки на підтримку і приводить розробників до конкурентних рішень.

Цей підручник присвячено звичаю написання документації API англійською: словниковий запас, структури речень, тон і шаблони, які роблять документацію зрозумілою для аудиторії у всьому світі.

Програма дає можливість переглядати документацію

Перед тим, як писати, знайдіть свою аудиторію:

** Розробники інтеграції ** — створення програм, які використовують ваш API
** Розробники інтерфейсу/мобільного програмування** — використовують ваші API сервера
** DevOps engineers ** — автоматизація робочих процесів за допомогою API
Команди продуктів у компаніях-партнерах — оцінка вашого API на предмет можливості

Всі вони потребують: ** що робить ця кінцева точка, що відправляти, що очікувати назад, і що може піти не так **.

Основний словник для документації API

Term	Meaning
endpoint	A specific URL that the API exposes: `GET /users/{id}`
resource	The entity the API manages: user, order, product
request	What the client sends to the API
response	What the API returns
payload / body	The data sent in the request body (JSON, XML)
query parameter	A key-value pair in the URL: `?limit=10&offset=0`
path parameter	A variable embedded in the URL path: `/users/{id}`
header	Metadata sent with the request: `Authorization`, `Content-Type`
status code	HTTP code in the response: 200 OK, 404 Not Found, 429 Too Many Requests
schema	The structure and types of request/response data
authentication	Proving who you are (API key, Bearer token, OAuth)
rate limiting	Restricting how many requests a client can make in a time period
idempotent	An operation that produces the same result regardless of how many times it is called
pagination	Splitting large result sets across multiple requests
deprecation	Announcing that an endpoint or parameter will be removed in a future version

Шаблон стандартної документації кінцевої точки

Кожен опис кінцевої точки повинен відповідати цій структурі:

### [HTTP METHOD] /path/to/endpoint

[One sentence describing what this endpoint does.]

**Authentication:** [Required / Not required — specify type: Bearer token / API key]

**Path Parameters**

| Name  | Type   | Required | Description       |
|-------|--------|----------|-------------------|
| id    | string | Yes      | The user's unique identifier |

**Query Parameters**

| Name   | Type    | Required | Default | Description               |
|--------|---------|----------|---------|---------------------------|
| limit  | integer | No       | 20      | Number of results to return (max: 100) |
| offset | integer | No       | 0       | Number of results to skip for pagination |

**Request Body** (for POST / PUT / PATCH)

[Schema with field name, type, required/optional, description]

**Responses**

| Status | Description            |
|--------|------------------------|
| 200    | Success — returns [resource] object |
| 400    | Bad request — invalid parameter |
| 401    | Unauthorized — missing or invalid token |
| 404    | Not found — [resource] with given ID does not exist |
| 429    | Rate limit exceeded — retry after `Retry-After` seconds |

**Example Request**

\`\`\`bash
curl -X GET "https://api.example.com/v1/users/u_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"
\`\`\`

**Example Response**

\`\`\`json
{
  "id": "u_abc123",
  "email": "alex@example.com",
  "role": "admin",
  "created_at": "2025-01-15T09:30:00Z"
}
\`\`\`

Стиль написання документації API. Name

Використовувати теперішній час

Документація API описує те, що система ** робить зараз **, а не те, що вона зробить або зробила.

❌ “Кінечна точка поверне список користувачів.” ✅ “Повертає список користувачів.”

❌ “Параметри limit обмежать кількість результатів.” ✅ “Параметри limit обмежують кількість результатів.”

Починати описи кінцевих точок з дієслова

Перше речення опису кінцевої точки має починатися з ** дієслова ** у третій особі однини.

❌ Avoid	✅ Prefer
This endpoint is for creating users	Creates a new user account
You can use this to retrieve orders	Returns all orders for the authenticated user
Used to delete a record	Deletes the specified record permanently

Поширені дієслова відкриття: ** Повертає, Створює, Оновлює, Вилучає, Отримання, Надіслав, Перевіряє, Скасував, Список, Пошук, Позначає**

Вимагати проти Необов’язковий — Зробити його явним

Ніколи не залишайте неоднозначним питання про те, чи потрібний параметр.

❌ ” email — адреса електронної пошти користувача” ✅ ” email (обов’язкове) — адреса електронної пошти користувача. Має бути коректною адресою електронної пошти. Максимум 255 символів.»

Написати про помилку, а не тільки про щасливий шлях

Більшість документів API описують, що відбувається, коли все йде добре. У чудовій документації описано, що відбувається, коли щось йде не так:

Як виглядає тіло помилки 400? Наведіть приклад.
Що робить 422 проти 400?
Що повинен робити розробник, щоб відновити роботу після кожної помилки?

** Приклад документації щодо відповіді на помилку: **

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request body contains invalid fields.",
    "details": [
      {
        "field": "email",
        "issue": "Must be a valid email address"
      },
      {
        "field": "age",
        "issue": "Must be a positive integer"
      }
    ]
  }
}

Шаблони для спільних розділів

Розділ автентифікації

## Authentication

All requests to the API require authentication using a Bearer token.

Include your token in the `Authorization` header of every request:

\`\`\`
Authorization: Bearer YOUR_API_TOKEN
\`\`\`

You can find your API token in your [Dashboard → API Settings](#).

**Do not expose your API token in client-side code** — treat it as a secret. If your token is compromised, rotate it immediately from the Dashboard.

Розділ обмеження швидкості

## Rate Limiting

The API enforces rate limits to ensure availability for all users.

| Plan  | Limit             |
|-------|-------------------|
| Free  | 100 requests/min  |
| Pro   | 1,000 requests/min|
| Enterprise | Custom    |

When you exceed the rate limit, the API returns **429 Too Many Requests** with a `Retry-After` header indicating how many seconds to wait before retrying.

\`\`\`
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712345678
\`\`\`

Розділ сторінок

## Pagination

All list endpoints support cursor-based pagination.

| Parameter | Type    | Default | Description                              |
|-----------|---------|---------|------------------------------------------|
| limit     | integer | 20      | Number of results per page. Maximum: 100 |
| cursor    | string  | —       | Cursor from the previous response's `next_cursor` field |

**Response structure:**

\`\`\`json
{
  "data": [...],
  "pagination": {
    "total": 1420,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6MTAwfQ=="
  }
}
\`\`\`

To fetch the next page, pass the `next_cursor` value as the `cursor` parameter in your next request.

Повідомлення про застарівання

> ⚠️ **Deprecated:** This endpoint is deprecated as of API v2 and will be removed on **June 30, 2026**.
> 
> Please migrate to [POST /v2/users](#post-v2-users) before the sunset date.
> 
> See the [migration guide](#) for step-by-step instructions.

Changelog / API версії мови

Під час документування змін і версій API, скористайтеся таким стандартним словником:

Change type	English phrasing
New endpoint added	”Added: `GET /v2/users/search` endpoint”
Parameter added	”Added optional `include_archived` parameter to `GET /users`”
Parameter deprecated	”Deprecated: The `legacy_id` field. Use `id` instead.”
Breaking change	”Breaking: The response schema for `GET /orders` has changed. The `items` field is now an array of objects instead of an array of strings.”
Bug fix	”Fixed: `POST /webhook` endpoint now correctly returns 201 on creation instead of 200.”
Removed	”Removed: `DELETE /v1/users/batch` — this endpoint was deprecated in v1.4.”

RFC 2119 Модальні дієслова

Документація API часто використовує RFC 2119 ключові слова, які мають певні технічні значення. Правильне використання цих символів свідчить про професійну документацію:

Keyword	Meaning
MUST	Absolute requirement. If you do not do this, the request will fail.
MUST NOT	Absolutely forbidden.
SHOULD	Strongly recommended, but not required. Valid reasons to ignore it may exist.
SHOULD NOT	Not recommended, but not forbidden.
MAY	Optional — permitted but not required.

** Приклад використання: **

“Заголовок Content-Type МІСТО встановити на application/json.”
“Клієнти ДОЛЖНИ реалізувати експоненційне відключення при обробці відповідей 429.”
“Поле metadata МОЖЕ містити будь-який чинний об’єкт JSON.”

Поширені помилки в документації API

1. Європейський Союз Неоднозначні описи параметрів

❌ ” sort — порядок сортування” ✅ *” sort — Порядок сортування результатів. Прийняті значення: asc (у зростаючому порядку) або desc (у спадному порядку). Типовий: desc

2-й. Немає прикладів відповідей на помилки

Розробникам найбільше потрібні приклади, коли щось йде не так, а не коли все йде добре.

3. Старі приклади

Якщо ваш API змінюється, але приклади не оновлюється, вони стають шкідливі. Зберігати приклади для перевірки — ідеально, щоб вони були автоматично створені з тестів.

4-й. Непослідовний англійський стиль

Виберіть голос (імператив для інструкцій, третя особа для описів) і дотримуйтесь його у всіх кінцевих точках.

5-й. Відсутній параметр « коли використовувати »

Особливо для схожих кінцевих точок (PUT vs. PATCH, offset vs. cursor pagination), пояснити, коли кожен з них є відповідним.

Practice

Список мов світу Vocabulary Study Set — 15 основних API-термінів з визначеннями
Використання: API документації — читати і відповідати на запитання про справжню документацію API
Письменницькі вправи — записує описи кінцевих точок і повідомлення про помилки