Англійською мовою: Reading API Documentation: A Practice Guide

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

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

---

Анатомія сторінки посилання API

Більшість сторінок документації REST API мають таку ж структуру. Як тільки ви впізнаєте частини, навігація стає набагато швидшою.

1. Опис кінцевої точки

У першому розділі наведено назви функцій кінцевої точки. Зазвичай, у ній використовується коротка імперативна фраза:

• “Створює новий обліковий запис користувача.” *
• “Отримує список активних підписок.” *
• « Вилучає вказаний ресурс назавжди. » *

Ключовий словник:

Verb	Meaning in API context
Retrieves	Gets data without modifying it (equivalent to GET)
Creates	Makes a new record (POST)
Updates	Modifies an existing record (PUT or PATCH)
Deletes	Removes a record (DELETE)
Returns	Describes what the response contains
Accepts	Describes what the request body must contain

2-й. Метод і шлях HTTP

POST /v1/users
GET  /v1/users/{user_id}

Шлях часто містить path параметри — змінні, що показуються в квадратних дужках {user_id} або з двокрапкою :user_id. У документації буде описано, яким типом є ці параметри і які значення є коректними.

Фраза, яку ви часто читаєте: * « Параметр шляху {user_id} має бути коректним UUID. » *

3. Параметри запиту

Параметри діляться на три типи, у документації завжди вказано, до якої категорії належить кожен з параметрів:

• ** Параметри шляху ** — частина самої адреси URL: /users/{id}
• ** Параметри запиту ** — додаються до адреси URL після ? : /users?status=active&limit=50
• Request body — відсилається як JSON в тілі запиту POST/PUT/PATCH

Для кожного параметра у документації описано:

• ** Назва ** — ключ параметра
• Тип — string, integer, boolean, array, object
• ** Обов’ язковий / Необов’ язковий ** — чи призведе його відсутність до помилки
• Description — що воно робить і які значення є коректними
• ** Типовий ** — якщо не обов’ язковий, значення, яке буде використано, якщо параметр буде опущено

** Підказка щодо читання: ** Перед читанням опису завжди перевіряйте, чи позначено параметр як * обов’ язковий *. Цей пункт негайно повідомить вас, чи можна його пропустити.

4-й. Схема тіла запиту

Для запитів POST і PUT у документації показано очікувану структуру JSON. Ви побачите такий словник:

Term	Meaning
Schema	The structure/shape of the JSON object
Property	A field in the JSON object
Nested	A property that is itself an object or array
Enum	A fixed list of allowed values, e.g. `“status”: “active"
Nullable	The value can be null in addition to its stated type
Required fields	Must be present or the request will fail
Optional fields	Can be omitted; defaults apply

** Приклад речення з документації: **

• “Властивість metadata не обов’ язкова. Якщо надано, це має бути об’єкт пар ключ-значення, де ключі є рядками до 40 символів.”*

Відповідь

Документація описує, що ви отримуєте назад. Стандартний словник:

• “Повертає 200 OK зі створеним об’ єктом.”
• “Повертає відповідь 201 Created з ресурсом у тілі.”
• • “Повертає порожню відповідь 204 No Content при успішному завершенні.” *
• • « Тіло відповіді — це масив об’ єктів користувача. » *

Фраза ** « при успішному завершенні » ** означає, що ця відповідь буде надіслано лише у тому випадку, якщо запит було виконано успішно і операція завершилася без помилок.

Схеми відповідей використовують той самий словник, що і схеми запитів, але ви також побачите:

• ** Розташування на сторінках ** — відповіді, які містять великий список, розділений на декілька сторінок
• ** Страникування за допомогою курсора ** — використовує знак next_cursor замість номерів сторінок
• ** Envelope ** — зовнішній об’ єкт обгортки, наприклад, { "data": [...], "meta": {...} }

6. Коди помилок

Цей розділ має критичне значення під час зневадження. У документації наведено список кодів стану HTTP, які може повертати кінцева точка, і їх значення у контексті.

Спільні шаблони:

Code	Standard meaning	Typical API context
400 Bad Request	Invalid input	Missing required field, wrong type, failed validation
401 Unauthorized	Not authenticated	Missing, expired, or invalid API key/token
403 Forbidden	Not authorised	Authenticated but lacks permission for this resource
404 Not Found	Resource does not exist	Wrong ID, deleted resource, wrong endpoint path
409 Conflict	Conflict with current state	Duplicate record, concurrent modification
422 Unprocessable Entity	Semantic error	Request is valid JSON but the values make no sense (e.g. end date before start date)
429 Too Many Requests	Rate limit exceeded	Slow down; retry after the Retry-After header value
500 Internal Server Error	Server-side failure	Not your fault; the API is broken

** Корисний словник у відповідях на помилки: **

• • “Запит було відхилено, оскільки поле email не пройшло перевірку формату.” *
• • “Стартовий термін дії наданого токена закінчився. Повторно автентифікуйтесь і спробуйте знову
• • « Обмеження швидкості 100 запитів за хвилину було перевищено. » *

Приклади коду

Більшість документації API включає приклади коду на декількох мовах (curl, JavaScript, Python тощо). Якщо англійський опис є заплутаним, приклад коду часто робить намір ясним.

Приклад curl особливо корисний, оскільки у ньому показано точну структуру запиту HTTP — заголовки, адресу URL, тіло — без будь- якої абстракції, властивої для певної мови.

---

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

Перед окремими кінцевими точками більшість документації API містить розділ Автентифікація. Загальний словник:

Term	Meaning
API key	A secret string sent in a header or query param to identify the caller
Bearer token	An OAuth 2.0 access token, sent as Authorization: Bearer <token>
OAuth 2.0	A standard protocol for delegated authorization
Scopes	Permissions granted to a token, e.g. read:users, write:billing
Rate limiting	Restrictions on how many requests can be made in a time window
Throttling	The mechanism that enforces rate limits

** Поширене речення: ** * “Всі запити повинні містити заголовок Authorization з чинним символом Bearer. Токени скасовуються через 3600 секунд.»*

---

Словник документації GraphQL

У документації GraphQL використовується інший словник, ніж у REST:

Term	Meaning
Query	A read operation (equivalent to GET)
Mutation	A write operation (equivalent to POST/PUT/DELETE)
Subscription	A real-time data stream
Resolver	The function that fetches the data for a field
Schema	The complete type definition of the API
Type	A defined object shape in the schema
Field	A property on a type
Argument	A parameter passed to a field
Fragment	A reusable set of fields

---

Практична стратегія читання

Коли відкриваєте сторінку довідки щодо API:

1. ** Спочатку прочитайте опис кінцевої точки ** — зрозумійте, що вона робить, у одному реченні
2. ** Визначити обов’ язкові і необов’ язкові параметри ** — перегляньте таблицю параметрів на предмет « обов’ язкових » маркерів перед читанням описів
3. ** Перевірте розділ кодів помилок ** — особливо коди 400 і 422, які свідчать про те, які перевірки було впроваджено
4. ** Прочитати приклад коду ** — якщо опис не є зрозумілим, приклад зазвичай його пояснює
5. ** Зауважте обмеження швидкості ** — їх легко пропустити і це може призвести до помилок у виробництві

---

Звичайні плутані фрази

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

Phrase	What it means
”idempotent”	Calling it multiple times has the same effect as calling it once
”deprecated”	Still works but will be removed in a future version; do not use in new code
”backwards compatible”	Old clients will still work after this change
”breaking change”	Old clients will break; migration required
”eventually consistent”	The response may not immediately reflect your last write
”at most once”	The operation may not execute if the system fails
”at least once”	The operation may execute more than once; callers must handle duplicates

---

Практика читання

Застосуйте ці навички до справжньої документації під час роботи. Якщо ви зустрінете фразу, яку ви не розумієте, пошукайте її у контексті — не лише у визначенні у словнику, а й у описі конкретної кінцевої точки.

Добрі публічні API для практики: GitHub REST API, Stripe API, Twilio API, PagerDuty API. Вони добре написані, використовують послідовний словник і покривають широкий спектр спільних шаблонів.

---

• Див. також: API Vocabulary для розробників, Писання документації API англійською, Інформаційний портал англійською *