10 помилок, які роблять розробники при написанні API (і як їх виправити)

Блогер та розробник Марк Анрі розповів про головне помилки, які допускають розробники при створенні API.

Пропонуємо вам переклад його його авторського блогу від нашої редакції. Далі — слово автору.

Кілька років тому я працював над проектом, який сильно залежав від стороннього API.

Все виглядало чудово. Документація була блискучою. Але що сталося, коли я зробив перший запит?

Бум.

500 Internal Server Error. Жодного повідомлення про помилку. Жодної підказки, що пішло не так. Лише холодний цифровий ляпас.

Звучить знайомо?

Якщо ви розробник, який коли-небудь створював API, швидше за все, ви ненавмисно скоїли деякі з гріхів, про які я зараз розповім.

Не хвилюйтеся — я теж це пережив.

Але настав час припинити завдавати болю і почати створювати чисті, зручні для користувачів API.

Давайте розглянемо 10 помилок API, за які вас зненавидять колеги-розробники, і дізнаємося, як їх уникнути, як професіонал.

1. Незрозумілі повідомлення про помилки

«Щось пішло не так».

О, дякую.

Якщо ваш API відповідає такими нечіткими повідомленнями, ви нікому не допомагаєте.

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

Виправте це:

Використовуйте правильні коди статусу HTTP. Поєднайте їх із детальними відповідями про помилки у форматі JSON.

{
  "error": {
    "code": 400,
    "message": "Invalid email format.",
    "field": "email"
  }
}

2. Ігнорування стандартів HTTP, ніби вони необов’язкові

Підказка: Вони не є необов’язковими.

GET ніколи не повинен змінювати дані. POST не є заміною для всього. PUT і PATCH — це не одне й те саме.

Неправильне використання цих дієслів — це як використовувати молоток, щоб розмішати каву.

Виправте це:

Дотримуйтесь специфікації. Вивчіть дієслова.

3. Відсутність версій

Вітаємо! Ви щойно зламали всі клієнтські програми своїм новим оновленням.

API потребують версій.

Відсутність версій — це як випустити програмне забезпечення без номерів версій і просто сказати: «Удачі».

Виправте це:

Вкажіть версію API в URL-адресі або заголовках.

GET /api/v1/users

4. Непослідовні правила іменування

Це user_id, UserIdчи userid? Виберіть одне. Дотримуйтесь його.

І заради всього, що пов’язано з JSON, не змішуйте camelCase і snake_case в одному відповіді.

Виправте це:

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

5. Відсутність пагінації

Повертаєте 10 000 записів в одній відповіді?

Сміливий крок. Сміливий… і жахливий.

Виправте це:

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

GET /api/v1/users?limit=50&offset=100

6. Погана документація (або її відсутність)

Немає документації? Можна просто дати розробникам чистий аркуш паперу і сказати: «Розберіться самі».

Виправте це:

Використовуйте Swagger, Postman, Redoc або будь-який інший інструмент для створення реальної, корисної документації. Додайте приклади коду.

Зробіть початок роботи дуже простим.

7. Надто складна автентифікація

Для створення запиту потрібні токен OAuth, підписаний заголовок, магічна руна і ваш первісток.

Серйозно?

Виправте це:

Забезпечте безпеку, але не ускладнюйте.

Використовуйте галузеві стандарти, такі як OAuth2 або API-ключі в заголовках.

Authorization: Bearer YOUR_TOKEN_HERE

8. Невикористання правильних кодів статусу

Припиніть повертати 200 OK для кожного запиту, включаючи помилки.

404 означає, що не знайдено. 401 означає, що доступ заборонено. 500 означає, що винакоїли.

Виправте це:

Використовуйте правильні коди. Це не складно. Ви можете знайти їх у Google.

9. Відсутність обмеження швидкості

Ваш сервер щойно завис, тому що хтось заспамив ваш кінцевий пункт 10 000 запитів на секунду.

Вітаємо.

Виправте це:

Впровадьте обмеження швидкості. Захистіть свій API та своїх користувачів.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

10. Відсутність тестування (так, серйозно)

Якщо ви не тестуєте свій API, то хто це робить? Ваші користувачі?

Надія — це не стратегія.

Виправте це:

Напишіть тести інтеграції. Використовуйте тести Postman.

Перевірте ваші кінцеві точки за допомогою таких інструментів, як Newman або REST Assured.

На закінчення

API — це вхідні двері до вашої системи. Чи хотіли б ви, щоб ваші гості заходили в двері без ручки, з заплутаними знаками та ризиком ураження електричним струмом?

Не думаю.

Створіть API, які розробники люблять використовувати. Зробіть їх інтуїтивно зрозумілими, передбачуваними та толерантними.

Ваше майбутнє «я» (і кожен розробник, який буде використовувати ваш API) буде вам вдячне.