Наиболее распространенные лучшие практики RESTful API


Описание

Существует множество руководств, описывающих лучшие практики проектирования Restful API. Это краткая подборка и резюме некоторых наиболее распространенных правил, которые вы можете найти в Интернете.

Правила

  1. Отправка и получение данных

    • Используйте JSON для всех коммуникаций
    • Ваш API не имеет статических данных
    • Разрешить фильтрацию, сортировку и пагинацию
    • Используйте правильный метод HTTP
    • Ответ должен быть предсказуемым
  2. Соглашения об именовании

    • Используйте существительные вместо глаголов в конечных точках
    • Называйте коллекции существительными во множественном числе
    • Используйте вложенность ресурсов
  3. Возвращать информацию об ошибке в теле ответа

  4. Безопасность

    • ИСПОЛЬЗУЙТЕ SSL/TLS
    • Защитите свой API
  5. Документируйте свой API

1. Отправка и получение данных

1.1 Используйте JSON для всех коммуникаций

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

1.2 Ваш API является Stateless

Это означает, что каждый запрос рассматривается как новый запрос. Ваш API не должен хранить никаких сведений о клиенте для будущих запросов. API не будет хранить учетные данные пользователя, токены или другую информацию, содержащуюся в заголовке/теле запроса.

1.3 Разрешить фильтрацию, сортировку и пагинацию

База данных может стать очень большой, особенно если в вашем API реализовано поведение, подобное CMS. Используйте общие ключевые слова и ограничения по умолчанию, чтобы ваши запросы к базе данных были быстрыми и эффективными.

Часто используемые ключевые слова для использования в фильтрах:

Limit (default=20) = Max returned items
Offset = Items to skip, allows for pagination
Sort = Sort/order the list by property value
Filter = Allows for searching by property name
Войти в полноэкранный режим Выйти из полноэкранного режима

1.4 Используйте правильный метод HTTP

Существует несколько типов HTTP-методов, которые вы можете использовать для определения конечной точки API. Это также позволяет использовать некоторые конечные точки повторно, но с другим HTTP-методом. Например, у вас может быть 2 конечные точки api/cars. Одна для GET и одна для POST. Используйте это в своих интересах.

POST CREATE = 201, ИЛИ 404, ЕСЛИ :ID НЕ НАЙДЕН, ИЛИ 409, ЕСЛИ ID УЖЕ СУЩЕСТВУЕТ
GET READ = 200, ИЛИ 404, ЕСЛИ :ID НЕ НАЙДЕН
PUT UPDATE/REPLACE 200, ИЛИ 404, ЕСЛИ :ID НЕ НАЙДЕН
PATCH UPDATE/MODIFY 200, ИЛИ 404, ЕСЛИ :ID НЕ НАЙДЕН
DELETE УДАЛИТЬ 200, ИЛИ 404, ЕСЛИ :ID НЕ НАЙДЕН

1.5 Ответ должен быть предсказуемым

Все в API должно быть последовательным. Если пользователь отправляет JSON в конечную точку с именем /products, она должна вернуть JSON. Возможно, даже с сообщением об ошибке. В свою очередь, вы никогда не должны возвращать ошибку в HTML или возвращать PDF файл, если он не ожидается.

2. Соглашения об именовании

2.1 Именование коллекций существительными во множественном числе

Если вы разрешаете создавать коллекцию из нескольких элементов, вам следует использовать множественное число в соглашении об именовании.
Не использовать

Использовать

2.2 Используйте существительные вместо глаголов в конечных точках

Не использовать

Использовать

2.3 Использовать логическую вложенность

Не использовать

Использовать

3. Обработка ошибок

3.1 Возвращайте описания ошибок в теле

Если что-то идет не так, например, валидация, вы можете захотеть сообщить пользователю, что именно пошло не так.

{
    "ResponseStatus": {
         "ErrorCode": "MissingRequiredField",
         "Message": "Property 'Message' is missing"
    }
}
Войти в полноэкранный режим Выйти из полноэкранного режима

4. Безопасность

4.1 Защита вашего API

Некоторые пользователи могут не иметь разрешения на доступ к вашему API. Подумайте заранее и запишите, кто должен и не должен иметь доступ к вашим данным. Возможно, у некоторых пользователей есть доступ на чтение, но нет доступа на удаление. Распространенным методом является использование аутентификации на основе токенов.

5. Документируйте свой API

Другим разработчикам должно быть легко использовать ваш API. Использование автоматизированной документации, такой как SWAGGER, поможет и вам, и вашим пользователям получить представление о конечных точках. Также рассмотрите возможность написания документации о том, как пользователи могут аутентифицироваться или запрашивать ваши конечные точки.

Резюме

Выполнение этих шагов должно сделать ваш API предсказуемым и пригодным для использования в производственных средах. Возможно, вам не удастся применить эти правила во всех приложениях, которые вы создаете. Большинство руководств по лучшей практике приводят примеры, как будто за ними стоит CMS, и предлагают простые примеры для конечных точек GET и POST. Но в реальной жизни приложения могут делать что-то более сложное, например, вычисления или изменять вход и выход.

Счастливого кодирования!

Оцените статью
Procodings.ru
Добавить комментарий