День восемьсот девяносто седьмой. #BestPractices
Лучшие Практики Использования RESTful API. Окончание
Начало

5. Аккуратно обрабатывайте ошибки
Вы должны аккуратно обрабатывать ошибки и возвращать соответствующие коды ответа HTTP, когда ошибка произошла. Коды ответа HTTP предоставят достаточно информации, чтобы понять причину ошибки и возникшую проблему.
Вот список распространённых кодов ответа HTTP:
- 400 Bad Request – неправильный запрос со стороны клиента
- 401 Unauthorized – неавторизованный клиент пытается получить доступ к ресурсу
- 403 Forbidden – клиент аутентифицирован, но не имеет прав для доступа к определённому ресурсу
- 404 Not Found – запрошенный ресурс не найден
- 415 Unsupported Media Type – клиент отправляет данные в формате, который не поддерживается сервером или для данного URI
- 422 Unprocessable Entity – клиент отправляет данные в понятном серверу формате, но сервер не может их обработать (например, отправлен неверный тип объекта)
- 500 Internal server error – сервер столкнулся с непредвиденными обстоятельствами, мешающими ему исполнить запрос
- 502 Bad Gateway – веб-сервер, к которому вы подключились, действует как прокси-сервер для ретрансляции информации с другого сервера, но получил неверный ответ от этого другого сервера
- 503 Service Unavailable – что-то неожиданное случилось на стороне сервера, и API недоступен.

Полезно возвращать подробные сведения об ошибке в теле ответа. Это поможет разработчикам выполнить отладку и обнаружить причину проблемы. Например:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "Неверный запрос.",
  "detail": {
    "address": "Поле address является обязательным."
  }
}

Следует последовательно использовать коды состояния. Например, если вы использовали 200 OK для конечной точки GET, вы должны использовать один и тот же код состояния для всех конечных точек GET. Вот примеры кодов ответа на разные типы запросов для обеспечения единообразия:

GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content

6. Избегайте использования глаголов в URI
Вы не должны описывать выполняемое действие с помощью глаголов в URL-адресе. Использование глаголов в REST API - плохая практика. Сам метод HTTP - это глагол: GET, PUT, POST, DELETE, - а URL-адрес всегда должен содержать существительные. Из этого правила есть несколько исключений. Например, глаголы используются для некоторых конкретных действий:

/login
/logout
/register

7. Повышение производительности
- Про использование формата JSON вместо XML мы уже говорили выше.
- Используйте вызовы PATCH, когда объём данных, подлежащих обновлению, небольшой. В запросе PATCH обычно передаётся особый тип данных, говорящий серверу, какие поля объекта следует изменить, и как.
- Ограничьте количество полей, возвращаемых API. В большинстве случаев не требуется возвращать полное представление ресурса. Уменьшая количество полей, вы сможете минимизировать сетевой трафик и повысить производительность API.

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

Источник: https://www.developer.com/web-services/best-practices-restful-api/