Содержание
Разработчик собрал топ ошибок в REST API, которые раздражают всех: как их избежать и сделать удобный API без проблем с безопасностью и UX
По данным Postman, 70% разработчиков сталкиваются с неудобными API, которые мешают работе.
Многие из них спроектированы с типичными ошибками. Один из разработчиков составил список самых раздражающих проблем и дал советы, как их избежать.
Ошибка №1: API, завязанный на внутренней структуре
Проблема: API отражает внутреннюю логику, заставляя клиентов разбираться в БД.
⛔ GET /api/database/tables/book_inventory/records?status=1
✅ GET /api/books?available=true
API должен быть понятным пользователю, а не разработчику системы.
Ошибка №2: Кривые URL и HTTP-методы
Некоторые API добавляют глаголы в пути или усложняют структуру.
⛔ POST /api/deleteCustomer/456
✅ DELETE /api/customers/456
Также не стоит делать глубокую вложенность. Например:
Как упаковать бэкенд-код на Go для аналитики на базе Sparktproger.ru
⛔ GET /api/companies/456/departments/2/employees/123/projects
✅ GET /api/projects?employeeId=123
Ошибка №3: Игнорирование обработки ошибок
⛔ Самый раздражающий ответ:
{ "error": "Something went wrong" }
✅ Как правильно:
{ "status": 400, "code": "INVALID_PARAMETER", "message": "The email address is invalid" }
Четкие коды ошибок экономят время и нервы разработчиков.
Ошибка №4: Отсутствие версионирования
Если API обновляется без версионирования, старые клиенты ломаются. Пример правильного подхода:
GET /api/v1/users
Accept: application/vnd.company.api+json;version=1
Важно не удалять старые версии без предупреждения.
Ошибка №5: Слишком много данных в ответах
Распространенная проблема — это когда API отдает всю информацию, даже если она не нужна.
Куда правильнее будет позволять клиенту выбирать поля (fields=id,name,email) и Делить данные на отдельные запросы (GET /api/users/123/orders).
Ошибка №6: Проблемы с безопасностью
Одной из самых частых ошибок с точки зрения безопасности является передача токенов в URL (?token=123). Также начинающие разработчики реализуют API, в которых отсутствуют ограничения запросов (Rate Limit) или используется HTTP вместо HTTPS.
Исправить это достаточно просто. Нужно использовать OAuth2/JWT и ограничивать частоту (HTTP 429).
Ошибка №7: Плохая документация
Вместе с тем важно понимать, что без нормальной документации, API никто не будет использовать.
Что такое вебхук и чем он отличаются от APItproger.ru
Наиболее частые проблемы по этой части:
- Нет примеров кода
- Непонятно, как авторизоваться
- Ошибки не объясняются
Хороший API — это не только код, но и удобство его использования. Не делайте так, чтобы разработчики вас ненавидели.