curl -X GET https://5b38d239-f95b-45a9-99a7-5706470b2995.mock.pstmn.io/todos/1
{
"id": 1,
"todo": "Do something nice for someone I care about",
"completed": true,
"userId": 26
}
Несмотря на большое количество правил и рекомендаций которые описаны в спецификации HTTP, их все равно недостаточно для построения полноценного API. Есть множество вопросов, на которые HTTP не отвечает:
Именно поэтому для построения хорошего API недостаточно правил HTTP, нужны дополнительные соглашения. За время существования интернета было создано немало стандартов API. Среди них можно выделить несколько больших направлений, которые строятся по примерно одинаковым правилам. Ниже мы их рассмотрим.
Сюда попадают все API, которые делают по принципу "как получится". Обычно они встречаются во внутренних сервисах или публичных старых сервисах, созданных десятки лет назад. Здесь нет никаких правил, каждый эндпоинт существует сам по себе, активно используются параметры запроса и игнорируются возможности самого HTTP, например коды ответа. В этом списке присутствуют лишь для того, чтобы показать, что реальный мир не такой красивый как нам бы того хотелось.
REST архитектурный стиль, который был заложен в сам HTTP (один из авторов HTTP является создателем REST). Не вдаваясь в подробности, скажем, что API построенный по этому принципу, вовсю использует возможности HTTP. Такое API активно опирается на заголовки, коды ответов, грамотно созданные эндпоинты. Например https://dummyjson.com/ построен по принципам REST. То есть, можно сказать, что глобальная идея REST в том, чтобы использовать для проектирования API возможности заложенные в HTTP изначально. Пример:
Метод | Маршрут | Описание |
---|---|---|
GET | /photos | список фотографий |
POST | /photos | создание фотографии |
GET | /photos/:id | данные фотографии |
PATCH/PUT | /photos/:id | обновление фотографии |
DELETE | /photos/:id | удаление фотографии |
Однако, REST не отвечает на те вопросы, которые были заданы в начале урока. REST это архитектурный стиль, а не конкретный стандарт. Например в эндпоинтах выше мы видим адреса и методы HTTP, но мы ничего не знаем про то какими будут данные в запросах и в ответах. Поэтому любое REST API имеет какие-то свои особенности, которые присущи только ему, например, то, как обрабатываются ошибки и какая структура у возвращаемых данных.
Существуют попытки создать стандарт, который добавляет в REST все недостающие части. Самым удачным из них является jsonapi. Этот стандарт описывает конкретные структуры данных для разных типов запросов и ответов. Например так может выглядеть извлечение конкретной фотографии:
{
"type": "photos",
"id": "1",
"attributes": {
"title": "Rails is Omakase"
},
"relationships": {
"author": {
"links": {
"self": "/photos/1/relationships/author",
"related": "/photos/1/author"
},
"data": { "type": "people", "id": "9" }
}
}
}
RPC API появились в интернете практически раньше всех остальных видов API. Общая идея RPC в том, что HTTP рассматривается всего лишь как способ доставки (транспорт), но, сам по себе, не является частью API. Как правило RPC API работают с одним эндпоинтом, например, /rpc
, на который отправляется GET или POST. RPC API используют небольшое количество заголовков и кодов ответов. Обработка ошибок, выполнение разных действий, все это в RPC зашито в само тело запроса и ответа.
Первоначальная идея RPC была в том, что мы как будто бы просто вызываем обычные функции, а они магическим образом делают запросы на внешнюю систему полностью или почти полностью скрывая от нас существование HTTP и сети в целом.
Например, запрос в JSON-RPC выглядит как JSON, в котором указывается то, какая "функция" и с какими параметрами должна быть вызвана:
{
"jsonrpc": "2.0",
"method": "subtract",
"params": { "minuend": 42, "subtrahend": 23 },
"id": 3
}
В ответе приходит результат вызова этой "функции":
{
"jsonrpc": "2.0", "result": 19, "id": 3
}
Разновидностей RPC очень много и они сильно отличаются между собой. Из наиболее известных можно назвать NFS, SOAP, XML-RPC, JSON-RPC, gRPC, GraphQL.
При разработке приложения, которое работает с чужим API часто возникает необходимость убедиться, что приложение работает и выполняет запросы. Это может быть как клиентское (фронтенд) приложение, так и серверное (бэкенд), которое обращается на внешний сервис. Для разработки и тестирования есть различные инструменты, которые позволяют не создавать реальное приложение с API, а создать заглушки. Такую возможность предоставляет и Postman, позволяя создать mock сервер, который отдает готовый ответ на указанные запросы.
Для создания Mock сервера вам необходима коллекция API. Создайте её, если её еще нет. Например коллекцию для Todos
Следуя документации создайте Mock сервер для созданной ранее коллекци.
Выполните запросы к созданному серверу (через браузер или curl). Пример запроса и ответа:
curl -X GET https://5b38d239-f95b-45a9-99a7-5706470b2995.mock.pstmn.io/todos/1
{
"id": 1,
"todo": "Do something nice for someone I care about",
"completed": true,
"userId": 26
}
В результате у вас получится созданный Mock сервер для коллекции Postman. Сервер на все запросы будет отвечать заготовленными ранее ответами, адрес созданного сервера будет доступен публично.
Вам ответят команда поддержки Хекслета или другие студенты.
Базовый план откроет полный доступ ко всем курсам, упражнениям и урокам Хекслета, проектам и пожизненный доступ к теории пройденных уроков. Подписку можно отменить в любой момент.
Курсы программирования для новичков и опытных разработчиков. Начните обучение бесплатно.
Наши выпускники работают в компаниях:
С нуля до разработчика. Возвращаем деньги, если не удалось найти работу.
Зарегистрируйтесь или войдите в свой аккаунт
Задавайте вопросы, если хотите обсудить теорию или упражнения. Команда поддержки Хекслета и опытные участники сообщества помогут найти ответы и решить задачу