Введение в REST API — RESTful веб-сервисы
Intro to RESTful Web Services
REST означает REpresentational State Transfer (Википедия: «передача состояния представления»). Это популярный архитектурный подход для создания API в современном мире.
Вы изучите:
- Что такое REST?
- На чем основан REST API?
- Как используется HTTP при создании REST API?
- Что такое ресурс?
- Как вы определяете ресурсы REST API?
- Каковы лучшие практики при разработке REST API?
Что такое REST?
REST расшифровывается как REpresentational State Transfer. Это был термин, первоначально введен Роем Филдингом (Roy Fielding), который также был одним из создателей протокола HTTP. Отличительной особенностью сервисов REST является то, что они позволяют наилучшим образом использовать протокол HTTP. Теперь давайте кратко рассмотрим HTTP.
Краткий обзор HTTP
Давайте сначала откроем браузер и зайдем на веб-страницу:
А затем щелкните на одной из страниц результатов:
Далее мы можем нажать на ссылку на странице, на которой мы оказались:
И перейти на другую страницу:
Вот как мы обычно просматриваем веб страницы.
Когда мы просматриваем страницы в Интернете, за кулисами происходит много вещей. Ниже приведено упрощенное представление о том, что происходит между браузером и серверами, работающими на посещаемых веб-сайтах:
Протокол HTTP
Когда вы вводите в браузере URL-адрес, например www.google.com, на сервер отправляется запрос на веб-сайт, идентифицированный URL-адресом.
Затем этот сервер формирует и выдает ответ. Важным является формат этих запросов и ответов. Эти форматы определяются протоколом HTTP — Hyper Text Transfer Protocol.
Когда вы набираете URL в браузере, он отправляет запрос GET на указанный сервер. Затем сервер отвечает HTTP-ответом, который содержит данные в формате HTML — Hyper Text Markup Language. Затем браузер получает этот HTML-код и отображает его на экране.
Допустим, вы заполняете форму, присутствующую на веб-странице, со списком элементов. В таком случае, когда вы нажимаете кнопку «Submit» (Отправить), HTTP-запрос POST отправляется на сервер.
HTTP и RESTful веб-сервисы
HTTP обеспечивает базовый уровень для создания веб-сервисов. Поэтому важно понимать HTTP. Вот несколько ключевых абстракций.
Ресурс
Ресурс — это ключевая абстракция, на которой концентрируется протокол HTTP. Ресурс — это все, что вы хотите показать внешнему миру через ваше приложение. Например, если мы пишем приложение для управления задачами, экземпляры ресурсов будут следующие:
- Конкретный пользователь
- Конкретная задача
- Список задач
URI ресурса
Когда вы разрабатываете RESTful сервисы, вы должны сосредоточить свое внимание на ресурсах приложения. Способ, которым мы идентифицируем ресурс для предоставления, состоит в том, чтобы назначить ему URI — универсальный идентификатор ресурса. Например:
- Создать пользователя: POST /users
- Удалить пользователя: DELETE /users/1
- Получить всех пользователей: GET /users
- Получить одного пользователя: GET /users/1
REST и Ресурсы
Важно отметить, что с REST вам нужно думать о приложении с точки зрения ресурсов:
Определите, какие ресурсы вы хотите открыть для внешнего мира
Используйте глаголы, уже определенные протоколом HTTP, для выполнения операций с этими ресурсами.
Вот как обычно реализуется служба REST:
- Формат обмена данными: здесь нет никаких ограничений. JSON — очень популярный формат, хотя можно использовать и другие, такие как XML
- Транспорт: всегда HTTP. REST полностью построен на основе HTTP.
- Определение сервиса: не существует стандарта для этого, а REST является гибким. Это может быть недостатком в некоторых сценариях, поскольку потребляющему приложению может быть необходимо понимать форматы запросов и ответов. Однако широко используются такие языки определения веб-приложений, как WADL (Web Application Definition Language) и Swagger.
Компоненты HTTP
HTTP определяет следующую структуру запроса:
- строка запроса (request line) — определяет тип сообщения
- заголовки запроса (header fields) — характеризуют тело сообщения, параметры передачи и прочие сведения
- тело сообщения (body) — необязательное
- строка состояния (status line), включающая код состояния и сообщение о причине
- поля заголовка ответа (header fields)
- дополнительное тело сообщения (body)
Методы HTTP-запроса
Метод, используемый в HTTP-запросе, указывает, какое действие вы хотите выполнить с этим запросом. Важные примеры:
- GET: получить подробную информацию о ресурсе
- POST: создать новый ресурс
- PUT: обновить существующий ресурс
- DELETE: Удалить ресурс
Код статуса ответа HTTP
Код состояния всегда присутствует в ответе HTTP. Типичные примеры:
- 200 — успех
- 404 — cтраница не найдена
Резюме
В статье приведен на верхнем уровне обзор архитектурного стиля REST. Подчеркивается тот факт, что HTTP является основным строительным блоком REST сервисов. HTTP — это протокол, который используется для определения структуры запросов и ответов браузера. Мы видели, что HTTP имеет дело главным образом с ресурсами, доступными на веб-серверах. Ресурсы идентифицируются с помощью URI, а операции над этими ресурсами выполняются с использованием глаголов, определенных протоколом HTTP.
Наконец, мы рассмотрели, как службы REST наилучшим образом используют функции, предлагаемые HTTP, для предоставления ресурсов внешнему миру. REST не накладывает никаких ограничений на форматы представления ресурсов или на определение сервиса.
Что такое API RESTful?
RESTful API — это интерфейс,используемые двумя компьютерными системами для безопасного обмена информацией через Интернет. Большинство бизнес-приложений должны взаимодействовать с другими внутренними и сторонними приложениями для выполнения различных задач. Например, чтобы генерировать ежемесячные платежные ведомости, ваша внутренняя бухгалтерская система должна обмениваться данными с банковской системой вашего клиента, чтобы автоматизировать выставление счетов и взаимодействовать с внутренним приложением по учету рабочего времени. RESTful API поддерживают такой обмен информацией, поскольку они следуют безопасным, надежным и эффективным стандартам программного взаимодействия.
Что такое API?
Интерфейс прикладного программирования (API) определяет правила, которым необходимо следовать для связи с другими программными системами. Разработчики внедряют или создают API-интерфейсы, чтобы другие приложения могли программно взаимодействовать с их приложениями. Например, приложение с табелем рабочего времени содержит API, который запрашивает полное имя сотрудника и диапазон дат. Получив эту информацию, интерфейс внутренне обрабатывает табель рабочего времени сотрудника и возвращает количество часов, отработанных за указанный период.
Таким образом, сетевой API функционирует как шлюз между клиентами и ресурсами в Интернете.
Клиенты
Клиенты — это пользователи, которые хотят получить доступ к информации в Интернете. Клиентом может быть человек или программная система, использующая API. Например, разработчики могут создавать программы, которые получают доступ к данным о погоде из метеосистемы. Также получить доступ к этим данным можно из браузера, посетив веб-сайт с информацией о погоде.
Ресурсы
Ресурсы — это информация, которую различные приложения предоставляют своим клиентам. Ресурсы могут быть изображениями, видео, текстом, числами или данными любого типа. Компьютер, который предоставляет ресурсы клиенту, также называется сервером. API позволяет организациям совместно использовать ресурсы и предоставляет веб-службы, обеспечивая безопасность, контроль и аутентификацию. Кроме того, API помогает определить, какие клиенты могут получить доступ к определенным внутренним ресурсам.
Что такое REST?
Representational State Transfer (REST) — это программная архитектура, которая определяет условия работы API. Первоначально REST создавалась как руководство для управления взаимодействиями в сложной сети, такой как Интернет. Архитектуру на основе REST можно использовать для поддержки высокопроизводительной и надежной связи в требуемом масштабе. Ее можно легко внедрять и модифицировать, обеспечивая прозрачность и кросс-платформенную переносимость любой системы API.
Разработчики могут создавать API с использованием нескольких архитектур. API-интерфейсы, соответствующие архитектурному стилю REST, называются REST API. Веб-службы, реализующие архитектуру REST, называются веб-службами RESTful. Как правило, термин RESTful API относится к сетевым RESTful API. Однако REST API и RESTful API являются взаимозаменяемыми терминами.
Ниже приведены некоторые принципы архитектурного стиля REST:
Единый интерфейс
Единый интерфейс является конструктивной основой любого веб-сервиса RESTful. Это указывает на то, что сервер передает информацию в стандартном формате. Отформатированный ресурс в REST называется представлением. Этот формат может отличаться от внутреннего представления ресурса в серверном приложении. Например, сервер может хранить данные в виде текста, но отправлять их в формате представления HTML.
Единый интерфейс накладывает четыре архитектурных ограничения:
- Запросы должны идентифицировать ресурсы. Это происходит за счет единого идентификатора ресурсов.
- Клиенты имеют достаточно информации в представлении ресурса, чтобы при желании изменить или удалить ресурс. Сервер выполняет это условие, отправляя метаданные, которые дополнительно описывают ресурс.
- Клиенты получают информацию о дальнейшей обработке представлений. Сервер реализует это, отправляя описательные сообщения, где содержатся метаданные о том, как клиент может использовать их оптимальным образом.
- Клиенты получают информацию обо всех связанных ресурсах, необходимых для выполнения задачи. Сервер реализует это, отправляя гиперссылки в представлении, чтобы клиенты могли динамически обнаруживать больше ресурсов.
Отсутствие сохранения состояния
В архитектуре REST отсутствие сохранения состояния относится к методу связи, при котором сервер выполняет каждый клиентский запрос независимо от всех предыдущих запросов. Клиенты могут запрашивать ресурсы в любом порядке, и каждый запрос либо изолирован от других запросов, либо его состояние не сохраняется. Это конструктивное ограничение REST API подразумевает, что сервер может каждый раз полностью понять и выполнить запрос.
Многоуровневая система
В многоуровневой системной архитектуре клиент может подключаться к другим авторизованным посредникам между клиентом и сервером и по-прежнему получать ответы от сервера. Серверы также могут передавать запросы другим серверам. Вы можете спроектировать свою веб-службу RESTful для работы на нескольких серверах с несколькими уровнями (безопасностью, приложениями и бизнес-логикой), совместно выполняющих клиентские запросы. Эти уровни остаются невидимыми для клиента.
Емкость кэша
Веб-службы RESTful поддерживают кэширование, то есть процесс сохранения некоторых ответов на клиенте или на посреднике для сокращения времени ответа сервера. Например, вы заходите на веб-сайт с общими изображениями верхнего и нижнего колонтитулов на каждой странице. Каждый раз, когда вы посещаете новую страницу веб-сайта, сервер должен повторно отправлять одни и те же изображения. Чтобы избежать этого, клиент кэширует или сохраняет эти изображения после первого ответа, а затем использует изображения из кэша. Веб-службы RESTful управляют кэшированием с помощью ответов API, которые определяют себя как кэшируемые или некэшируемые.
Код по запросу
В архитектурном стиле REST серверы могут временно расширять или настраивать функциональные возможности клиента, передавая код программного обеспечения. Например, когда вы заполняете регистрационную форму на каком-либо веб-сайте, ваш браузер сразу же выделяет все допущенные ошибки (например, неверные номера телефонов). Это происходит благодаря коду, отправленному сервером.
В чем заключаются преимущества RESTful API?
RESTful API обладает следующими преимуществами:
Возможность масштабирования
Системы, реализующие REST API, могут эффективно масштабироваться благодаря оптимизации взаимодействия между сервером и клиентом по REST. Отсутствие сохранения состояния снимает нагрузку с сервера: серверу не нужно сохранять информацию о предыдущих запросах клиента. Отлаженное кэширование частично или полностью устраняет некоторые взаимодействия между клиентом и сервером. Перечисленные функции предполагают масштабируемость и не ограничивают пропускную способность, что может привести к снижению производительности.
Гибкость
Веб-службы RESTful поддерживают полное разделение клиента и сервера. Они упрощают и разделяют различные серверные компоненты, чтобы каждая часть могла развиваться независимо. Изменения платформы или технологии в серверном приложении не влияют на клиентское приложение. Возможность разделения функций приложения на уровни еще больше повышает гибкость. Например, разработчики могут вносить изменения в уровень базы данных, не переписывая логику приложения.
Независимость
REST API не зависит от используемой технологии. Вы можете создавать как клиентские, так и серверные приложения на разных языках программирования, не затрагивая структуру API. Также можно изменить базовую технологию на любой стороне, не влияя на обмен данными.
Как работает RESTful API?
Базовый принцип работы RESTful API совпадает с принципом работы в Интернете. Клиент связывается с сервером с помощью API, когда ему требуется какой-либо ресурс. Разработчики описывают принцип использования REST API клиентом в документации на API серверного приложения. Ниже представлены основные этапы запроса REST API:
- Клиент отправляет запрос на сервер. Руководствуясь документацией API, клиент форматирует запрос таким образом, чтобы его понимал сервер.
- Сервер аутентифицирует клиента и подтверждает, что клиент имеет право сделать этот запрос.
- Сервер получает запрос и внутренне обрабатывает его.
- Сервер возвращает ответ клиенту. Ответ содержит информацию, которая сообщает клиенту, был ли запрос успешным. Также запрос включает сведения, запрошенные клиентом.
Сведения о запросе и ответе REST API могут немного различаться в зависимости от того, как разработчики проектируют API.
Что содержит клиентский запрос RESTful API?
API RESTful требует, чтобы запросы содержали следующие основные компоненты:
Уникальный идентификатор ресурса
Сервер присваивает каждому ресурсу уникальный идентификатор ресурса. В случае со службами REST сервер идентифицирует ресурсы с помощью универсального указателя ресурсов (URL). URL указывает путь к ресурсу. URL аналогичен адресу веб-сайта, который вы вводите в браузере для посещения веб-страницы. URL также называется адресом запроса и четко указывает серверу, что требуется клиенту.
Метод
Как правило, разработчики реализуют RESTful API с помощью протокола передачи гипертекста (HTTP). Метод HTTP сообщает серверу, что ему необходимо сделать с ресурсом. Ниже приведены четыре распространенных метода HTTP:
Клиенты используют GET для доступа к ресурсам, расположенным на сервере по указанному URL. Они могут кэшировать запросы GET и отправлять параметры в запросе RESTful API, чтобы сообщить серверу о необходимости фильтровать данные перед отправкой.
Клиенты используют POST для отправки данных на сервер. При этом они включают в запрос представления данных. Отправка одного и того же запроса POST несколько раз имеет побочный эффект — многократное создание одного и того же ресурса.
Клиенты используют PUT для обновления существующих на сервере ресурсов. В отличие от POST, отправка одного и того же запроса PUT несколько раз дает один и тот же результат в веб-службе RESTful.
DELETE
Клиенты используют запрос DELETE для удаления ресурса. Запрос DELETE может изменить состояние сервера. Однако если у пользователя нет соответствующей аутентификации, запрос завершается ошибкой.
Заголовки HTTP
Заголовки запросов — это метаданные, которыми обмениваются клиент и сервер. Например, заголовок запроса указывает формат запроса и ответа, предоставляет информацию о статусе запроса и т. д.
Данные
Запросы REST API могут включать данные для успешной работы POST, PUT и других методов HTTP.
Параметры
Запросы RESTful API могут включать параметры, которые предоставляют серверу более подробную информацию о необходимых действиях. Ниже приведены некоторые типы параметров:
- Параметры пути, которые определяют детали URL.
- Параметры запроса, которые запрашивают дополнительную информацию о ресурсе.
- Параметры cookie, которые быстро аутентифицируют клиентов.
Что такое методы аутентификации RESTful API?
Веб-служба RESTful должна аутентифицировать запросы для последующей отправки ответа. Аутентификация — это процесс подтверждения личности. Например, для подтверждения личности можно использовать удостоверение личности или водительские права. Точно так же клиенты службы RESTful должны подтвердить свою личность серверу, чтобы установить доверие.
RESTful API поддерживает четыре распространенных метода аутентификации:
HTTP-аутентификация
HTTP определяет некоторые схемы аутентификации, которые можно использовать при реализации REST API. Ниже представлены две такие схемы:
Базовая аутентификация
При базовой аутентификации клиент отправляет имя пользователя и пароль в заголовке запроса. Он кодирует их с помощью метода кодирования base64, который преобразует пару имя пользователя–пароль в набор из 64 символов для безопасной передачи.
Аутентификация носителя
Аутентификация носителя — это процесс предоставления управления доступом носителю токена. Как правило, токен носителя представляет собой зашифрованную строку символов, которую сервер генерирует в ответ на запрос входа в систему. Клиент отправляет токен в заголовках запроса для доступа к ресурсам.
Ключи API
Ключи API — это еще один вариант аутентификации REST API. При таком подходе сервер генерирует уникальное значение и присваивает его первому клиенту. Всякий раз, когда клиент пытается получить доступ к ресурсам, он использует для верификации уникальный ключ API. Ключи API менее надежны: поскольку клиент должен передавать ключ, повышается вероятность его кражи.
OAuth
OAuth сочетает в себе пароли и токены для безопасного входа в любую систему. Сначала сервер запрашивает пароль, а затем дополнительный токен для завершения процесса авторизации. Он может проверять токен в любое время, а также через определенный период времени в соответствии с областью и сроком действия.
Что содержит ответ сервера RESTful API?
Принципы REST требуют, чтобы ответ сервера содержал следующие компоненты:
Строка состояния
Строка состояния содержит трехзначный код состояния, который сообщает об успешном или неудачном выполнении запроса. Например, коды 2XX указывают на успешное выполнение, а коды 4XX и 5XX — на ошибки. Коды 3XX указывают на перенаправление URL.
Ниже приведены некоторые распространенные коды состояния:
- 200: общий ответ об успешном выполнении
- 201: ответ об успешном выполнении метода POST
- 400: неверный запрос, который сервер не может обработать
- 404: ресурс не найден
Текст сообщения
Текст ответа содержит представление ресурса. Сервер выбирает подходящий формат представления на основе содержания заголовков запроса. Клиенты могут запрашивать информацию в форматах XML или JSON: они определяют запись данных в виде обычного текста. Например, если клиент запрашивает имя и возраст человека по имени Джон, сервер возвращает представление JSON в следующем формате:
Заголовки
Ответ также содержит заголовки или метаданные об ответе. Они дают более подробный контекст ответа и включают такую информацию, как название сервера, кодировка, дата и тип контента.
Как AWS может помочь в управлении RESTful API?
Шлюз API Amazon – это полностью управляемый сервис для разработчиков, предназначенный для создания, публикации, обслуживания, мониторинга и обеспечения безопасности API в любых масштабах. API Gateway позволяет создавать RESTful API для приложений двусторонней связи в реальном времени.
С помощью API Gateway можно:
- Предоставить пользователям высокую производительность при запросах и ответах API.
- Разрешить доступ к API с помощью AWS Identity and Access Management (IAM) и Amazon Cognito, которые обеспечивают встроенную поддержку OAuth.
- Запускать несколько версий одного и того же API одновременно с помощью API Gateway, что позволяет быстро дорабатывать, тестировать и запускать новые версии.
- Отслеживать метрики производительности и информацию о запросах API, задержке данных и частоте ошибок из API Gateway.
Начните работу со шлюзом API, воспользовавшись нашим пошаговым руководством и создав аккаунт AWS уже сегодня.
Что такое REST API?
Этот курс ориентирован на практику, но, выполняя различные задания, будем периодически останавливаться и углубляться и в абстрактные, концептуальные понятия, чтобы разобраться в них более подробно. Здесь мы рассмотрим, что такое REST API, сравним его с другими типами API, такими как SOAP. API REST имеют общие характеристики, но не имеют однозначных протоколов, таких как его предшественник SOAP.
Что такое API
В общем, API (Application Programming Interface) обеспечивает взаимодействие между двумя системами. Это как винтик, связывающий две детали, или как шестеренка, при помощи которой приводятся в движение две соседние шестеренки (как на картинке ниже).
API часто получают данные из пользовательских интерфейсов. Джим Биссо, опытный технический писатель API в области Силиконовой долины, описал API, используя аналогию калькулятора компьютера. Когда нажимаем кнопки, скрытые функции взаимодействуют с другими компонентами для получения информации. Как только информация возвращается, калькулятор представляет данные обратно в графический интерфейс.
API работают аналогичным образом. При нажатии на кнопку в интерфейсе, запускаются внутренние функции, чтобы передать и получить информацию. Но вместо того, чтобы получать информацию из одной и той же системы, веб-API вызывают удаленные сервисы в сети, чтобы получить их информацию.
В конечном счете, разработчики вызывают API незримо для пользователя для извлечения информации в свои приложения. Кнопка в графическом интерфейсе пользователя программно подключена для вызова внешних служб. Например, кнопки Twitter или Facebook, которые взаимодействуют с социальными сетями, или видео Youtube, которые извлекают видео с youtube.com, работают под управлением веб-API.
API, использующие протокол HTTP = веб-сервисы
«Веб-сервис» — это веб-приложение, предоставляющее ресурсы в формате, используемом другими компьютерами. Веб-сервисы включают в себя различные типы API, в том числе REST и SOAP API. Веб-сервисы — это, в основном, запросы и ответы между клиентами и серверами (компьютер запрашивает ресурс, а веб-сервис отвечает на запрос).
API, использующие протокол HTTP для передачи запросов и ответов, рассматриваются как «веб-сервисы». В случае веб-сервисов клиент, делающий запрос на ресурс, и сервер API, предоставляющий ответ, могут использовать любой язык программирования или платформу. Не имеет значения, какой ЯП или платформа будут использоваться, потому что запрос сообщения и ответ сделаны через общий веб-протокол HTTP.
Веб-протокол является частью прекрасного веб-сервисов: они независимы от языка и поэтому совместимы между различными платформами и системами. При документировании REST API не имеет значения, строят ли инженеры API с помощью Java, Ruby, Python или какого-либо другого языка. Запросы выполняются через HTTP, и ответы возвращаются через HTTP.
Диаграмма ниже показывает общую модель REST API:
Как видно, между клиентом и сервером API существует запрос и ответ. Клиент и сервер могут быть основаны на любом языке, но HTTP — это протокол, используемый для передачи сообщения. Этот шаблон запроса и ответа, по сути, является принципом работы API REST.
Любой язык программирования, создающий запрос, будет по-своему отправлять веб-запрос и анализировать ответ на своем языке. Эти специфичные для языка функции отправки запросов и анализа ответов не являются частью REST API (хотя они могут быть предоставлены в прилагаемом SDK). REST API не зависит от языка и обрабатывает входящую и исходящую информацию по HTTP.
API-интерфейсы SOAP являются предшественниками REST API
До того, как REST стал самым популярным веб-сервисом, SOAP (Simple Object Access Protocol) был гораздо более распространенным. Чтобы лучше понять REST, полезно иметь некоторое понимание SOAP. Заодно и увидеть, что отличает SOAP и REST.
SOAP — это стандартизированный протокол, который требует XML в качестве формата сообщений для запросов и ответов. Как стандартный протокол, формат сообщения обычно определяется с помощью файла WSDL (язык описания веб-служб).
Файл WSDL определяет разрешенные элементы и атрибуты в обмениваемых сообщениях. Файл WSDL является машиночитаемым и используется серверами, взаимодействующими друг с другом для облегчения связи.
Сообщения SOAP заключены в «конверт», который включает в себя заголовок и тело, используя определенную схему XML и пространство имен. Пример формата запроса и ответа SOAP см. SOAP против REST 101: понимание различий.
Основная проблема с SOAP заключается в том, что формат сообщений XML слишком многословный и тяжелый. Особенно это проблематично в мобильных сценариях, где размер файла и пропускная способность играют решающее значение. Многословный формат сообщения замедляет время обработки, что делает взаимодействия SOAP вялым.
SOAP по-прежнему используется в enterprise приложениях (особенно в финансовых учреждениях) со связью server-to-server, но в последние годы SOAP вымещается REST, особенно для API открытых сетей.
REST — стиль, а не стандарт
Как и SOAP, REST (Representational State Transfer) использует HTTP в качестве протокола передачи данных для запросов и ответов. Однако, в отличие от SOAP, REST является архитектурным стилем, а не стандартным протоколом. Вот почему REST API иногда называют RESTful API — REST — это общий стиль, которому следует API.
API-интерфейс RESTful может не соответствовать всем официальным характеристикам REST, указанным доктором Роем Филдингом, который впервые описал эту модель. Следовательно, API являются «RESTful» или «REST-подобными». (Некоторые разработчики настаивают на использовании термина «RESTful», когда API не соответствует всем характеристикам REST, но большинство людей просто называют их «REST API»)
В архитектурном стиле нет ограничений XML в качестве формата сообщения. API REST могут использовать любой формат сообщений, который хотят использовать разработчики API, включая XML, JSON, Atom, RSS, CSV, HTML и другие.
Несмотря на разнообразие параметров формата сообщений, большинство API REST используют JSON (нотацию объектов JavaScript) в качестве формата сообщений по умолчанию. Они используют JSON, потому что он обеспечивает легкий, простой и более гибкий формат сообщений, который увеличивает скорость связи. Облегченная природа JSON также позволяет выполнять сценарии мобильной разработки и легок для парсинга в Интернете с помощью JavaScript.
Напротив, в XML, XSLT больше используется для представления или, скорее, «преобразования» («T» в XSLT) содержимого, хранящегося на языке XML. XSLT обеспечивает удобочитаемость (а не обработку данных, хранящихся в формате XML).
REST фокусируется на ресурсах, доступ к которым осуществляется через URL
Другой отличительной чертой REST является то, что API-интерфейсы REST фокусируются на ресурсах (то есть вещах, а не действиях) и способах доступа к ресурсам. Ресурсы, как правило, являются разными типами информации. Вы получаете доступ к ресурсам через URL (Uniform Resource Locators), так же как переход к URL-адресу в вашем браузере позволяет подключиться к информационному ресурсу. URL-адреса сопровождаются методом, который указывает, как вы хотите взаимодействовать с ресурсом.
Общие методы включают GET (чтение), POST (создание), PUT (обновление) и DELETE (удаление). Конечная точка обычно включает параметры запроса, которые определяют более подробную информацию о представлении ресурса, который нужно увидеть. Например, можно указать (в параметре запроса) ограничение на отображение 5 экземпляров ресурса.
Вот пример, как выглядит конечная точка:
http://apiserver.com/homes?limit=5&format=json Конечная точка показывает весь путь к ресурсу. Однако в документации вы обычно разделяете этот URL на более конкретные части:
- Базовый путь (базовый URL или хост) относится к общему пути для API. В приведенном выше примере базовый путь — http://apiserver.com;
- Отношение конечной точки к конечному пути этой точки. В приведенном примере это /homes ;
- ?limit=5&format=json часть конечной точки содержит параметры строки запроса для этой точки.
В приведенном выше примере конечная точка получит ресурс «homes» и ограничит результат до 5 домов. Будет возвращен ответ в формате JSON.
Можно иметь несколько конечных точек, которые ссылаются на один и тот же ресурс. Вот один из вариантов:
http://apiserver.com/homes/
Приведенный выше URL-адрес может быть конечной точкой, которая извлекает домашний ресурс, содержащий определенный идентификатор. То, что передается обратно с сервера на клиент, является «представлением» ресурса. Ресурс может иметь много разных представлений (показывая все дома или дома, которые соответствуют определенным критериям, или дома в определенном формате и т.д.), Но здесь мы хотим видеть дом с определенным идентификатором.
Tip: Отношения между ресурсами и методами часто описывается в терминах «существительные» и «глаголы». Ресурс — это существительное, потому что это объект или вещь. Глагол — это то, что вы делаете с этим существительным. Объединяя существительные с глаголами, вы формируете язык REST.
Более подробно рассмотрим конечные точки в следующих разделах (например, в Обзоре руководства описания API мы рассмотрим каждое свойство ресурса). А здесь дан краткий обзор.
Сама сеть следует за REST
Термины «запросы GET» и «ответы на сообщения», передаваемые по «протоколу HTTP», могут показаться незнакомыми, но это всего лишь официальная терминология REST для описания происходящего. Поскольку мы используем Интернет, мы уже знакомы с тем, как работают API-интерфейсы REST — сама сеть по сути следует стилю RESTful.
Когда мы открываем браузер и переходим на https://idratherbewriting.com, в действительности мы используем протокол HTTP ( http: // ) для отправки запроса GET на ресурс, доступный на веб-сервере. Ответ от сервера отправляет контент с этого ресурса обратно по протоколу HTTP. Наш браузер — это просто клиент, который делает ответ на сообщение читаемым и знакомым нашему глазу.
Можно увидеть этот ответ в curl, если открыть окно терминала и набрать curl https://idratherbewriting.com. (Предполагается, что curl установлен )
Сам Интернет является примером архитектуры стиля RESTful, а значит и то, как работают API REST, скорее всего, станет понятным тем, кто проходит этот курс.
API REST не сохраняют состояния запроса, но ответы могут кэшироваться
REST API не сохраняют свои состояния и могут кэшироваться. Отсутствие состояния означает, что каждый раз, когда вы обращаетесь к ресурсу через конечную точку, API предоставляет один и тот же ответ. Он не запоминает ваш последний запрос и не учитывает его при предоставлении нового ответа. Другими словами, нет ранее запомненных состояний, которые API учитывает при каждом запросе.
Ответы могут кэшироваться для повышения производительности. Если кэш браузера уже содержит информацию, запрашиваемую в запросе, браузер может просто вернуть информацию из кэша вместо того, чтобы снова стучаться на сервер.
Кэширование API REST аналогично кешированию веб-страниц. Браузер использует значение времени последнего изменения в заголовках HTTP, чтобы определить, нужно ли ему снова получать ресурс. Если содержимое не было изменено с момента последнего извлечения, вместо него можно использовать кэшированную копию. Кэширование увеличивает скорость ответа.
API REST имеют и другие характеристики, о которых можно узнать побольше в этом видео. Одна из таких характеристик включает ссылки в ответах, позволяющие пользователям переходить к дополнительным элементам. Эта функция называется HATEOS, или Hypermedia As The Engine of State.
Изучение подробной теории REST не является целью курса, также, как и незнание подробной теории не станет проблемой документирования REST API. Тем не менее, существует множество технических книг, курсов и веб-сайтов, в которых более подробно рассматриваются концепции, ограничения и архитектура REST API, к которым при желании можно обращаться. Например, посмотрите «Основы программирования: веб-сервисы» Дэвида Гасснера на lynda.com.
API REST не используют файлы WSDL, но некоторые спецификации все же существуют
Важным аспектом API REST, особенно в контексте документации, является то, что они не используют файл WSDL для описания элементов и параметров, разрешенных в запросах и ответах.
Хотя и существует возможный файл WADL (Web Application Description Language), который можно использовать для описания API-интерфейсов REST, им используются редко, поскольку там неадекватно описываются все ресурсы, параметры, форматы сообщений и другие атрибуты API-интерфейса REST. , (Помните, что REST API — это архитектурный стиль, а не стандартизированный протокол.)
Чтобы понять, как взаимодействовать с REST API, нужно прочитать документацию по API. Необходимость читать документы делает роль технического писателя чрезвычайно важной для документирования API.
Некоторые формальные спецификации — например, OpenAPI и RAML — были разработаны для описания API REST. Когда вы описываете свой API с использованием спецификации OpenAPI или RAML, инструменты, которые могут читать эти спецификации (например, Swagger UI или консоль RAML API), будут генерировать вывод интерактивной документации.
Спецификация OpenAPI может заменить файл WSDL, более распространенный в SOAP. Такие инструменты, как Swagger UI, которые читают документы спецификаций, обычно создают интерактивную документацию (с использованием API-консолей или API-проводников) и позволяют вам тестировать вызовы REST и просматривать ответы прямо в браузере.
Но не ожидайте, что выходные данные документации Swagger UI или RAML API Console будут содержать все детали, которые потребуются пользователям для работы с вашим API. Например, эти выходные данные не будут включать информацию о ключах авторизации, подробностях о рабочих процессах и взаимозависимостях между конечными точками и так далее. Вывод Swagger или RAML обычно содержит только адресную документацию, на которую обычно приходится только треть или половина всей необходимой документации (в зависимости от API).
В целом, API REST более разнообразны и гибки, чем API SOAP, и почти всегда нужно читать документацию, чтобы понять, как взаимодействовать с API REST. Изучая API-интерфейсы REST, можно обнаружить, что они значительно отличаются друг от друга (особенно формат и отображение сайтов документации, которые мы рассмотрим в обзоре сайтов документации API), но все они имеют общие принципы и паттерны. В основе любого REST API лежит запрос и ответ, передаваемые через Интернет.
Проектирование REST API: спорные вопросы с проектов и собеседований на системного аналитика (и не только)
Привет! Эта статья на холиварную тему. Комментарии приветствуются, особенно если у вас есть интересный опыт, которым можете поделиться!
Проектирование REST API — это процесс создания дизайна методов обмена данными. Дизайн — это субъективное. У одних «так», у других «сяк». А кто прав? Иногда все, а иногда нет.
В этой статье Системные аналитики, Backend-разработчики и Архитекторы найдут спорные вопросы с проектов и собеседований, которые связаны с созданием контрактов REST API.
Вопросы взяла по итогам общения с системными аналитиками, которые недавно проходили собеседования, с моего открытого вебинара, и из комментариев к серии постов про REST API в моем канале, где я рассказываю про него и показываю, как использовать на практике.
Спорные вопросы:
- Можно ли использовать метод POST для получения данных?
- Можно ли сделать в проекте все методы POST?
- Можно ли в GET передавать тело запроса?
- Как правильно именовать эндпоинты — ед. число или мн. число (/user или /users)?
- Как правильно строить URL — нужно ли писать create/update в названии метода?
- Какой код ответа на метод POST: 200 или 201?
- Что вернуть в ответ, если получен пустой результат — пустой массив или 404?
REST API — что это и для чего?
REST API — это архитектурный стиль, который определяет, по каким правилам приложения должны обмениваться данными между собой. Он используется для создания веб-сервисов, мобильных приложений, интеграционных платформ и других IT-решений.
Впервые был определен и описан Роем Филдингом в диссертации 2000-го года. Рой Филдинг — соавтор спецификаций HTTP и URI.
Главная цель REST API — облегчить передачу и управление информацией между разными системами: создавать, читать, изменять, удалять (CRUD). REST API использует для этого стандартные HTTP-запросы: GET, POST, PUT, DELETE и другие.
�� REST API — это архитектурный стиль проектирования взаимодействия приложений.
�� HTTP — протокол, на основе которого работает REST API.
Отличие REST API от других видов API, таких как SOAP API, ftp и RPC, заключается в том, что REST API не имеет жестких правил и структур, и может быть использован с любым языком программирования — Java, Python, C++ и другие.
Из-за того, что REST API не имеет жестких правил и структур, и возникают спорные вопросы, связанные с его проектированием.
1. Можно ли использовать метод POST для получения данных?
Да, можно.
Метод POST изначально предназначен для отправки данных на сервер с целью их обработки и создания новых записей в БД. В то же время его можно использовать для получение данных в следующих случаях:
1. Запросы на получение данных (списки объектов) с большим количеством фильтров
Когда необходимо реализовать большое количество фильтров для получения списка, то решение отправлять их все в URL запроса как query-параметры не лучшее, т.к. это делает URL очень длинным. Это может вызвать проблемы с ограничениями на длину URL в некоторых веб-серверах или браузерах.
Кроме того, сложные и многочисленные параметры в URL могут затруднить читаемость и понимание запроса для других разработчиков и пользователей API.
Допустим, у нас есть API для получения списка книг из базы данных. Пользователь может фильтровать этот список по автору, жанру, году публикации, издательству, рейтингу и многим другим параметрам. Если пытаться передать все эти фильтры в URL, то он может выглядеть так:
Метод "Получение списка книг с применением фильтров": GET https://test-system.com/api/books?author=Толстой&genre=роман&year=1877&publisher=Огонек&rating=5&. Такой подход делает URL громоздким и может привести к превышению ограничения на длину URL, особенно если захочется добавить еще больше фильтров.
Вместо этого, можно использовать метод POST для передачи всех этих параметров в теле запроса в формате JSON:
Метод "Создание поискового запроса на получение списка книг с применением фильтров": POST https://test-system.com/api/books/search
Такой подход делает запрос более структурированным и читаемым, избегая проблем с длиной URL. Кроме того, это позволяет легко расширять список фильтров в будущем без страха ограничений.
В двух этих примерах результат будет идентичный: тело ответа со списком книг, отфильтрованных по заданным пользователем параметрам.
Стоит отметить, что при выборе метода POST для таких запросов, необходимо четко документировать это поведение в API-документации, чтобы избежать путаницы среди пользователей API.
2. Асинхронные запросы на получение данных: комбинирование POST и GET
Асинхронные запросы на получение данных реализуются за счет комбинации методов POST и GET.
Асинхронные запросы часто используются в ситуациях, когда необходимо обработать большой объем данных или когда процесс может занять длительное время. Это могут быть запросы на формирование отчетов или сложные поисковые запросы в системах-агрегаторах.
Реализуются асинхронные запросы последовательным использованием методов:
- POST — используется для создания задачи на сервере. При получении такого запроса, сервер помещает задачу в очередь на обработку и возвращает идентификатор задачи.
- GET — с помощью этого метода можно проверить статус выполнения задачи, используя идентификатор, предоставленный на предыдущем шаге. Как только задача завершена, через этот же метод можно получить результаты его выполнения.
Отчеты: В больших системах формирование отчетов может требовать обработки огромных объемов данных, что занимает много времени. Вместо ожидания окончания процесса, пользователь может отправить запрос на формирование отчета и вернуться к нему позже.
1. Пользователь отправляет POST-запрос для формирования отчета по продажам. При этом в теле запроса передаются параметры, необходимые для формирования отчета, такие как диапазон дат, тип отчета или другие фильтры.
Метод размещения запроса на формирование отчета: POST /api/reports/sales
После обработки этого запроса сервер создает задачу на формирование отчета и помещает ее в очередь.
Cервер возвращает идентификатор задачи. Этот уникальный идентификатор позволяет пользователю отслеживать статус формирования отчета.
2. Через некоторое время пользователь может отправить GET-запрос, чтобы проверить, готов ли отчет или получить его, если он готов.
Метод получения информации по статусу формирования отчета или готового отчета: GET /api/reports/sales/status/
Если отчет еще формируется:
Если отчет уже готов, пользователь может скачать его, используя предоставленный URL в ответе или получить его структуру. Зависит от выбранного способа реализации.
Пример, если в ответ на отчет готова ссылка на его загрузку:
Сложные поисковые запросы: Системы-агрегаторы, такие как поисковики авиабилетов, иногда ищут информацию во внешних системах — поставщиках данных. Такой запрос может занять много времени, особенно если один или несколько внешних источников медленно отвечают на запросы.
Представим, что вы создаете API для системы бронирования авиабилетов. Пользователь хочет найти билеты на определенную дату.
1. Пользователь отправляет POST-запрос с деталями поиска (дата, пункт назначения и т.д.).
Метод размещения запроса на поиск авиабилетов: POST /api/tickets/search
Сервер возвращает идентификатор задачи — идентификатор созданного запроса на поиск.
2. Через некоторое время пользователь делает GET-запрос с этим идентификатором, чтобы узнать статус поиска.
Метод получения статуса или информации по результатам поиска, если он завершен: GET /api/tickets/search/ или GET /api/tickets/search/status/
Ответ (если поиск еще не завершен):
Как только поиск завершен, пользователь получает список доступных рейсов в ответ на GET-запрос.
Этот подход обеспечивает эффективное использование ресурсов сервера и хороший UX для пользователя, который не вынужден ждать завершения длительных операций, а может поставить задачу на получение данных в фон, или получать результаты поиска быстро и порциями, по мере сбора данных из разных систем (помните, когда во время поиска авиабилетов у вас постоянно добавляются новые и новые записи?).
Это лишь часть примеров, но они являются наиболее ярким подтверждением того, что POST может использоваться для получения данных.
2. Можно ли сделать в проекте все методы POST?
Можно, но не рекомендуется 🙂
Использование только методов POST в API — это не самое красивое решение, которое может вызывать вопросы. Однако понимание возможных причин и последствий такого подхода, может помочь принять, понять и простить.
Почему так могут делать:
- Универсальность: в теле запроса POST можно передавать большие объемы данных, что может быть удобно для сложных запросов, в том числе поисковых.
- Развитие действующего API: потому что так уже сделаны все методы API и сейчас разработчики продолжают поддерживать дизайн API в том же стиле.
- Другие причины: будет интересно почитать в комментариях.
Возможные проблемы такого подхода:
- Несоблюдение стандартов: Принципы REST подразумевают использование различных HTTP-методов для разных CRUD-операций (GET для получения, PUT для обновления и т.д.). Использование только POST может запутать разработчиков и усложнить интеграцию с вашей системой.
- Сложности кэширования: HTTP-кэширование обычно применяется к GET-запросам. Не критично.
- Отсутствие идемпотентности: Повторное выполнение одного и того же POST-запроса может привести к разным результатам. Не критично.
Примеры API-документации, где только POST-запросы:
В открытом доступе я знаю только про DaData. Хороший сервис, но почему-то все запросы реализованы через POST. Верю, что этому есть какое-то объяснение
3. Можно ли в GET передавать тело запроса?
Не стоит, оно будет проигнорировано или обрезано.
HTTP-спецификация не запрещает передачу тела запроса в методе GET, но этот подход считается нестандартным и может вызвать определенные проблемы и вопросы при разработке и использовании API.
Почему передача тела запроса в GET может показаться привлекательной? В некоторых сценариях может возникнуть потребность в передаче сложных данных для фильтрации или поиска, которые сложно или невозможно передать через URL в виде query-параметров.
Главная проблема такого подхода: не все клиенты и серверы поддерживают передачу тела запроса в методе GET. Некоторые из них могут игнорировать тело запроса или возвращать ошибку. Проще говоря, тело запроса будет проигнорировано или «обрезано».
Примеры исключений из правил, когда можно передавать тело в GET, привести не могу. Не встречала таких решений.
4. Как правильно именовать эндпоинты — ед. число или мн. число (/user или /users)?
Можно и так, и так. Но нужно ориентироваться на то, как названы остальные эндпоинты в проекте. В новом API я бы делала в ед. числе, т.к. у меня больше такого опыта, чем с мн.ч.
В именовании ресурсов в REST API есть разные подходы, и, честно говоря, нет строгого стандарта.
Однако на практике чаще всего предпочитают использовать единственное число для ресурсов. Но и множественное число также активно используется!
Согласно множественному подходу, даже если вы хотите получить информацию о конкретной задаче, вы все равно обращаетесь к «коллекции» задач и выбираете одну из них.
Примеры:
Единственное число:
GET /task/123 — получить информацию о задаче с ID 123.
POST /task — создать новую задачу.
Множественное число:
GET /tasks — получить список всех задач
GET /tasks/123 — получить информацию о задаче с ID 123.
POST /tasks — создать новую задачу.
Множественное число представляет собой коллекцию элементов, что соответствует идеологии REST для метода добавления нового элемента в коллекцию и чтения списка — /tasks читается легче, где у вас есть коллекция ресурсов и конкретные ресурсы внутри этой коллекции.
Рекомендации по множественному числу есть в гайдлайнах:
1) Microsoft API Guidelines: 7.4.1. POST —> POST http://api.contoso.com/account1/servers
2) Google Cloud API Design Guide: Resource names —> Example 1: A storage service has a collection of buckets, where each bucket has a collection of objects
При этом, если мы взглянем на Яндекс:
Наглядный пример как в рамках одной огромной компании работали разные команды.
От чего зависит выбор? От опыта команды, и как комфортнее воспринимать методы при чтении.
Помимо этих источников, хорошей практикой также является изучение и анализ популярных публичных API, чтобы увидеть общепринятые стандарты в сообществе. А лучшая практика — посмотрите как у вас уже реализован API в компании!
Важно помнить: вне зависимости от выбранного подхода, ключевым является его последовательное использование на протяжении всего проекта API.
Хотя я предпочитаю единственное число, для меня важнее договоренность с командой и поддержка единого подхода на протяжении всего проекта.
5. Как правильно строить URL — нужно ли писать create/update в названии метода?
Не рекомендуется так делать. Это считается плохим тоном.
В принципах RESTful дизайна, использование глаголов, таких как create или update , в URL считается плохой практикой. Идея REST заключается в
использовании стандартных HTTP-методов (GET, POST, PUT, DELETE и т. д.)
в сочетании с номинативными URL, представляющими ресурсы.
Типы методов и есть глаголы, дублирование глаголов create и update в URL избыточно. Не рекомендуется их дублировать в URL! Зачем? API и так прекрасно читается, если он спроектирован по стандартам RESTful и в нём не все POST!
Примеры:
- POST /products/create (использует глагол create )
- PATCH /products/update/123 (использует глагол update )
- POST /products (для создания нового продукта)
- PATCH /products/123 (для обновления продукта с идентификатором 123)
В целом, при разработке RESTful API рекомендуется избегать включения глаголов, описывающих действия, в URL.
6. Какой код ответа на метод POST: 200 или 201?
При правильном подходе к использованию метода POST для создания новых данных в БД рекомендуется на успешные операции отвечать HTTP-201 Created . Хотя HTTP-200 ОК тоже допустим, когда в результате выполнения запроса новые данные не создаются.
Выбор правильного кода ответа так же важен, как и структура запросов и ответов. Ответы HTTP имеют стандартизированные коды, которые передают определенный смысл клиентам API.
Метод POST обычно используется для создания нового ресурса — новых данных в БД. После успешного создания нового ресурса, наиболее подходящим кодом ответа является 201 Created . Он явно указывает на то, что запрос был успешно выполнен и в результате был создан новый ресурс.
200 OK также является допустимым кодом ответа для метода POST. Он обычно используется в ситуациях, когда POST-запрос не приводит к созданию нового ресурса, но успешно обработан. Такие ситуации могут включать в себя операции, которые вызывают некоторые действия на сервере или просто передают данные без их сохранения в базе данных.
Пример:
Метод для создания новых пользователей: POST /users
- HTTP-код: 201 Created
- Тело ответа: может включать информацию о новом пользователе или быть пустым.
При использовании метода POST для создания новых ресурсов в вашем RESTful API рекомендуется ответ с кодом 201 Created . Это не только соответствует стандартам HTTP, но и ясно передает намерение сервера клиенту или пользователю.
В любом случае, зафиксируйте в API-гайдлайнах вашей компании какой код ответа вы будете возвращать на POST в случае, если запрос не приводит к созданию данных. Это важно для развития API, чтобы вся команда, которая работает над одним проектом понимала внутренние правила проектирования.
7. Что вернуть в ответ, если получен пустой результат — пустой массив или 404?
Оба варианты допустимы и правильные. Зафиксируйте то, какой результат вы будете возвращать в случае пустых результатов в корпоративном REST API гайдлайне, чтобы команда разработки знала однозначный ответ на этот вопрос при развитии API. Клиенты API также должны быть проинформированы о том, какие результаты в этих случаях ожидать, и одинаково обрабатывать их.
Одной из основных дилемм при проектировании API является вопрос о том, как правильно ответить на запрос, когда искомые данные отсутствуют. Это актуально для ситуаций, когда клиент запрашивает список, но объекты данных в нем отсутствуют.
Вариант 1 — пустой массив:
Если клиент запрашивает список элементов, то наиболее логичным было бы вернуть пустой список (в формате JSON это будет пустой массив [] ), когда элементы отсутствуют. Это четко указывает на то, что запрос был корректным, и в текущий момент элементы отсутствуют.
Пустой массив позволяет клиентским приложениям без дополнительных проверок обрабатывать ответ, будь то пустой или полный список.
Вариант 2 — ошибка с кодом HTTP-404 Not Found: Код 404 Not Found явно указывает на то, что искомый ресурс отсутствует. Однако, при запросе списка ресурсов, это может вызвать путаницу, потому что 404 чаще ассоциируется с ситуацией, когда сам endpoint не найден (Помните, когда на сайтах страница не найдена, то пишут 404 Not Found?).
В то время как для списка ресурсов лучше возвращать пустой массив, для конкретного ресурса (например, конкретный пользователь или статья) 404 Not Found подходит, если он не существует.
Примеры:
Метод получения списка пользователей:
GET /users
Рекомендуемый ответ, если пользователи не найдены:
HTTP-код: 200 OK
Body ответа: []
Метод получения информации о пользователе с > GET /users/123
Рекомендуемый ответ, если пользователь не найден:
HTTP-код: 404 Not Found
Body ответа: нет.
При разработке RESTful API я бы рекомендовала везде возвращать 200 и пустой массив в случае отсутствия результатов по запросу, а не код ошибки 404 Not Found . А для получения информации об одном конкретном объекте как раз 404 Not Found .
Можно делать в обоих случаях 200 и [], можно делать в обоих случаях 404 ошибку, но моя настоятельная рекомендация: внесите рекомендации по стандарту ответа на такие ситуации в корпоративный гайдлайн по дизайну REST API и проинформируйте о принятом решении по обработке такого исключения клиентов вашего API.
Заключение
В статье нет ни единого слова про НУЖНО. Здесь я рассказала про негласные стандарты отрасли IT и свой опыт проектирования и тестирования REST API разных проектов.
То, что может быть идеальным решением для одного проекта или команды, может не подходить для других. Всегда важно подходить к проектированию REST API с учетом конкретных требований, контекста и потребностей вашего проекта.
При развитии REST API придерживайтесь тех правил, которые уже ранее были приняты в проекте и поддерживайте их. Если эти правила не зафиксированы — разработайте корпоративный гайдлайн по дизайну REST API. Т.е. если в API уже все POST, не надо умничать и добавлять GET. Это будет выбиваться из общей концепции и вызывать вопросы.
При создании нового REST API сразу вводите корпоративный гайдлайн по дизайну REST API и в нём фиксируйте:
- общие правила по дизайну методов:
- типы методов;
- дизайн URL эндпоинтов;
- коды ответов;
- реакция на типовые ошибки;
- и другие.
Документация и гайдлайны в проекте наше всё! Особенно в тех вопросах, где дело касается дизайна (хоть и программного интерфейса) и опыта команды.
Хорошие дизайнеры UI/UX делают гайдлайны для приложений, чтобы можно было развивать их и пользователи интуитивно понимали и чувствовали, что приложение сделано в одном визуальном стиле. В разработке API это тоже применимо!
Что еще почитать и посмотреть по REST API
Хорошо подойдет для тех, кто только пытается разобраться что это и зачем.
YouTube:
- Связь базы данных и дизайн REST API.
- Postman — навык тестирования REST API за вечер.
- REST API с нуля — дизайн методов для работы с заявками автосервиса.
База знаний GetAnalyst:
- Простыми словами про API.
- REST API с нуля до проектирования и тестирования методов — серия мини-блогов в телеграм про проектирование системы управления задачами на проекте.
Книги:
- «Проектирование веб-API», Арно Лоре.
- «CHAPTER 5. Representational State Transfer (REST)» — диссертация Роя Филдинга (англ).
P.S.
Какие еще спорные вопросы вы встречали по дизайну REST и какие решения по ним? Пишите в комментарии.
P.P.S.
Делитесь, когда у вас в компании принято использовать 400-е ошибки (ошибки клиента), а когда 500-е (ошибки сервера)?
Например, что вернете, если при создании нового города в справочнике обнаружили, что город с таким названием уже ранее был создан в БД (найден дубликат)?
- rest api
- restful api
- api
- системный анализ
- системный аналитик
- проектирование по
- проектирование взаимодействия
- backend
- backend-разработка
- json
- Анализ и проектирование систем
- Проектирование и рефакторинг
- IT-стандарты
- API