Лучшие практики в разработке API

#перевод_для_канала_itarchitecture

В повседневной работе в качестве инженеров-программистов большинство использует или создает REST API. Стандартный подход обеспечения коммуникации между системами - посредством API. Поэтому, чтобы избежать проблем в будущем, очень важно правильно проектировать REST API. Верно определенный API должен быть простым в работе, лаконичным и затруднять его неправильное использование.

Вот несколько общих рекомендаций:

1. Используйте существительные вместо глаголов

Глаголы не должны использоваться в конечных точках (endpoints). Вместо этого путь должен содержать существительные, которые идентифицируют объект, к которому принадлежит endpoint, объект, к которому мы обращаемся или который изменяем.

Например, вместо использования /getAllClients для получения всех клиентов используйте /clients.

2. Используйте существительные ресурса во множественном числе

Старайтесь использовать форму множественного числа для существительных ресурса, потому что это подходит для всех типов endpoints.

Например, вместо использования /employee/:id/ используйте /employees/:id/

3. API должны быть последовательными

Под последовательностью подразумевается предсказуемость. Поведение endpoints должно следовать единым правилам. Таким образом, используйте один и тот же подход для ресурсов, одни и те же методы аутентификации для всех endpoints, используйте одни и те же заголовки, используйте одни и те же коды состояния и т. д.

4. Сохраняйте API простыми

Мы должны сделать так, чтобы имена всех endpoints были ориентированы на сущности, с которыми они работают. Если мы хотим определить API для пользователей, мы бы определили его как:

/users
/users/124

Таким образом, первый API получает всех пользователей, а второй получает конкретного пользователя.

5. Используйте правильные коды состояния

Этот пункт особо важен. Есть много кодов состояния HTTP, но мы обычно используем только некоторые из них. Не используйте слишком много, но используйте одни и те же коды состояния для одних и тех же результатов в API, например,

- 200 - запрос выполнен успешно
- 201 - запрос выполнен успешно и привёл к созданию ресурса
- 400 - некорректный запрос
- 401 - несанкционированный запрос
- 403 - отсутствуют разрешения
- 404 - недостающие ресурсы
- 5xx - внутренние ошибки

6. Не возвращайте обычный текст

REST API должны принимать JSON для полезной нагрузки запроса, а также отвечать в формате JSON, так как это стандарт для передачи данных в REST. Тем не менее, недостаточно просто вернуть тело со строкой в формате JSON, нам также нужно указать заголовок Content-Type как application/json. Единственным исключением является отправка и получение файлов между клиентом и сервером.