Facebook, GitHub, Google и многим другим гигантам нужен способ обслуживания и использования данных. RESTful API
Но задумывались ли вы
Мы рассмотрим 13 лучших практик, которые следует учитывать при создании RESTful API. Но сначала давайте быстро проясним RESTful API.
Что такое RESTful API?
RESTful API должен соответствовать следующим ограничениям, чтобы его можно было назвать RESTful API.
Без сохранения состояния. Что еще более важно, RESTful API не должен иметь состояния. Каждый запрос рассматривается как отдельный запрос. Сервер не должен отслеживать
Единый интерфейс. Наконец, единообразие определяет, как взаимодействуют клиент и сервер.
Запрос PUT: создать или заменить ресурс
Запрос PATCH: обновить существующий ресурс
УДАЛИТЬ запрос: удалить ресурс
Благодаря более глубокому пониманию характеристик RESTful API пришло время узнать больше о передовых методах RESTful API.
Лучшие практики для разработки вашего первого RESTful API
В этой статье представлен действенный список из 13 лучших практик. Давайте исследовать!
1. Правильно используйте
Мы уже обсуждали возможные методы HTTP, которые вы можете использовать для изменения ресурсов: GET, POST, PUT, PATCH и DELETE.
Тем не менее, многие разработчики склонны злоупотреблять GET и POST или PUT и PATCH. Часто мы видим, как разработчики используют запрос POST для получения данных. Кроме того, мы видим, что разработчики используют запрос PUT, который заменяет ресурс, в то время как они хотели обновить только одно поле для этого ресурса.
Убедитесь, что вы используете правильный метод HTTP, так как это добавит много путаницы разработчикам, использующим ваш RESTful API. Лучше придерживаться намеченных рекомендаций.
2. Соглашения об именах
Понимание соглашений об именах RESTful API очень поможет вам в организованном проектировании вашего API. Разработайте RESTful API в соответствии с ресурсами, которые вы обслуживаете.
Например, ваш API управляет авторами и книгами (да, классический пример). Теперь мы хотим добавить нового автора или получить доступ к автору с идентификатором 3. Для этой цели можно разработать следующие маршруты:
api.com/addNewAuthor
api.com/getAuthorByID/3
Представьте себе API, в котором размещается множество ресурсов, каждый из которых имеет множество свойств. Список возможных конечных точек станет бесконечным и не очень удобным для пользователя. Поэтому нам нужен более организованный и стандартизированный способ проектирования конечных точек API.
В рекомендациях RESTful API описывается, что конечная точка должна начинаться с имени ресурса, а операция HTTP описывает действие. Теперь мы получаем:
ОТПРАВИТЬ api.com/authors
ПОЛУЧИТЬ api.com/authors/3
Что, если мы хотим получить доступ ко всем книгам, которые автор с ID когда- 3либо писал? Также для этого случая у RESTful API есть решение:
ПОЛУЧИТЬ api.com/authors/3/books
Наконец, что если вы хотите удалить книгу с идентификатором 5автора с идентификатором 3. Опять же, давайте следовать тому же структурированному подходу, чтобы сформировать следующую конечную точку:
УДАЛИТЬ api.com/authors/3/books/5
Короче говоря, используйте операции HTTP и структурированный способ сопоставления ресурсов, чтобы сформировать удобочитаемый и понятный путь к конечной точке. Большим преимуществом этого подхода является то, что каждый разработчик понимает, как устроены RESTful API, и может сразу же использовать API без необходимости читать вашу документацию по каждой конечной точке.
3. Используйте множественные ресурсы
Ресурсы всегда должны использовать форму множественного числа. Почему? Представьте, что вы хотите получить всех авторов. Следовательно, вы должны вызвать следующую конечную точку: GET api.com/authors.
Когда вы читаете запрос, вы не можете сказать, будет ли ответ API содержать только одного или всех авторов. По этой причине конечные точки API должны использовать несколько ресурсов.
4. Правильное использование кодов состояния
Коды состояния здесь не только для развлечения. У них есть четкая цель. Код состояния уведомляет клиента об успешном выполнении его запроса.
Наиболее распространенные категории кодов состояния включают в себя:
200 (ОК): запрос успешно обработан и выполнен.
201 (Created): указывает на успешное создание ресурса.
400 (неверный запрос): представляет собой ошибку на стороне клиента. То есть запрос был неправильно сформирован или отсутствуют параметры запроса.
401 (Unauthorized): вы пытались получить доступ к ресурсу, для которого у вас нет разрешения.
404 (не найдено): запрошенный ресурс не существует.
500 (внутренняя ошибка сервера): каждый раз, когда сервер вызывает исключение во время выполнения запроса.
Полный список кодов состояния можно найти на сайте Mozilla Developers. Не забудьте проверить код статуса «Я чайник» (418).
5. Соблюдайте правила использования регистров
Чаще всего RESTful API обслуживает данные JSON. Следовательно, следует практиковать соглашение о регистре camelCase. Однако разные языки программирования используют разные соглашения об именах.
6. Как работать с поиском, нумерацией страниц, фильтрацией и сортировкой
Такие действия, как поиск, разбиение на страницы, фильтрация и сортировка, не представляют собой отдельные конечные точки. Эти действия можно выполнить с помощью параметров запроса, которые предоставляются вместе с запросом API.
Например, давайте получим всех авторов, отсортированных по имени в порядке возрастания. Ваш запрос API должен выглядеть следующим образом: api.com/authors?sort=name_asc.
Кроме того, я хочу найти автора по имени «Михиль». Запрос выглядит так api.com/authors?search=Michiel.
К счастью, многие проекты API имеют встроенные возможности поиска, разбиения на страницы, фильтрации и сортировки. Это сэкономит вам много времени.
7. Версии API
Я нечасто сталкиваюсь с этим, но рекомендуется использовать версию API. Это эффективный способ сообщить пользователям о критических изменениях.
Часто номер версии API включается в
8. Отправлять метаданные через
Заголовки HTTP позволяют клиенту отправлять дополнительную информацию со своим запросом. Например, Authorizationзаголовок обычно используется для отправки данных аутентификации для доступа к API.
Полный список всех возможных заголовков HTTP можно найти здесь.
9. Ограничение скорости
Ограничение скорости — интересный подход к контролю количества запросов на одного клиента. Это возможные заголовки ограничения скорости, которые может возвращать ваш сервер:
10. Значимая обработка ошибок
Если
{
«status»: 400,
«message»: «Resource books does not exist»,
«code»: 24801,
«more_info»: «api.com/docs/errors/24801»
}
В этом примере сервер возвращает код состояния и удобочитаемое сообщение. Кроме того, разработчику также возвращается внутренний код ошибки для поиска конкретной ошибки. Это позволяет разработчику быстро найти дополнительную информацию об ошибке.
11. Выберите правильную структуру API
Существует множество фреймворков для разных языков программирования. Важно выбрать платформу, которая поддерживает лучшие практики RESTful API.
Для Node.js
12. Документируйте свой API
Наконец, напишите документацию! Я не шучу; это
Хотя ваш API соответствует всем передовым методам, изложенным для RESTful API, все же стоит потратить время на документирование различных элементов, таких как ресурсы, которые обрабатывает ваш API, или ограничения скорости, применяемые к вашему серверу.
Подумайте о своих
13. Будь проще!
Не усложняйте свой API и сохраняйте простоту ресурсов. Правильное определение различных ресурсов, с которыми работает ваш API, поможет вам избежать проблем, связанных с ресурсами, в будущем. Определите свои ресурсы, но также точно определите их свойства и отношения между ресурсами. Таким образом, нет места спорам о том, как соединить разные ресурсы.
