10 интересных открытых REST API для вашего следующего проекта
Давайте посмотрим правде в глаза — мир не нуждается в еще одном калькуляторе или приложении для ведения списка дел. Вместо этого задумайтесь о создании новых и интересных приложений вокруг открытых REST API.
У большинства разработчиков есть побочные или личные проекты. Но как начать делать такое новое приложение? Страшно сидеть перед пустым редактором, задаваясь вопросом, что делать…. Существует тысячи постов в блогах с советами начать программировать калькулятор, список дел или клон социальной сети. Хотя они, безусловно, могут быть полезны для изучения стека технологий, давайте посмотрим правде в глаза — мир не нуждается в еще одном калькуляторе или приложении для ведения списка дел. Вместо этого задумайтесь о создании новых и интересных приложений вокруг открытых REST API.
Что такое REST API?
Representable State Transfer(REST) Application Programming Interface(API) предоставляет набор методов, которые программист может использовать через HTTP для отправки и получения данных. Поскольку эти методы используют HTTP, любой язык программирования может работать с ними.
Сейчас доступны тысячи REST API практически на всех возможных сайтах. Обычно для общедоступных данных, таких как погода или фондовые рынки, вы можете найти десятки разных API, доступных для использования. Многие популярные веб-платформы, такие как Facebook и Twitter, также предоставляют API для разработчиков. Некоторые из проприетарных API имеют ограничения на количество обращений к ним. Многие требуют регистрации и получения закрытого ключа. Наиболее безопасные API требуют настройки OAuth для безопасного входа пользователей.
Вы можете найти огромный список публичных API на Github, а еще больший список существует на RapidAPI.
10 занятных REST API
Этот список, конечно, не является исчерпывающим, но просто некоторые из них я считаю особенно интересными и достойными ваших побочных проектов. Все они абсолютно бесплатны и не требуют ничего, кроме как получить API-ключ — не нужно разбираться, как обращаться с OAuth или платить за их использование.
Что с этим делать
Все эти общедоступные API прекрасны, но наличие списка интересных источников данных по своей сути не помогает решить проблему, связанную с новым проектом.
Лучше всего начать с простого получения и отображения данных. Может быть, показывать покемона дня или определение набранного слова. Для более креативного подхода попробуйте взять данные и добавить им наглядности — например, свяжите температуру с цветом или отобразите движение автобуса.
Самое сложное — это просто начать. После того, как вы преодолеете начальные препятствия в получении и отображении информации, я уверен, что вы придумаете множество возможностей для вашего проекта!
Используете какие-то другие REST API? Напишите нам, и мы добавим их в этот список!
REST API Best Practices
Привет, Хабр! Представляю вашему вниманию перевод статьи «REST API Best Practices» автора Krishna Srinivasan.
REST становится общим подходом для представления сервисов окружающему миру. Причина его популярности заключается в его простоте, легкости использования, доступе через HTTP и другие. Существует неправильное представление о том, что все данные, доступные через сеть, считаются REST, но это не так. В этой статье я собираюсь объяснить вам некоторые best practices, которые вы должны всегда помнить при реализации собственного REST приложения. Я бы хотел услышать ваш опыт в REST приложениях, поэтому если вы знаете best practies, которые не упомянуты в этой статье, пожалуйста, поделитесь с нами в комментариях.
Disclamer: все best practies основаны на моем личном опыте. Если вы имеете другое мнение, не стесняйтесь отправлять его мне на email, и мы обсудим его.
Здесь представлен список best practices, которые будут обсуждаться в этой статье:
1. Конечные точки в URL – имя существительное, не глагол
2. Множественное число
3. Документация
4. Версия вашего приложения
5. Пагинация
6. Использование SSL
7. HTTP методы
8. Эффективное использование кодов ответов HTTP
1. Конечные точки в URL – имя существительное, не глагол
Одна из самых распространённых ошибок, которую делают разработчики REST приложений, — использование глаголов при именовании конечных точек. Однако, это не лучшая практика. Вы должны всегда использовать существительные вместо глаголов.
Мы имеем заказ на разработку REST веб сервисов, которые предоставляют информацию об Индийских фермерах. Сервис также должен реализовывать функционал, предоставляющий такую информацию как доход фермера, названия культур, адреса ферм и другую информацию, относящуюся к каждому фермеру. Каждый фермер имеет уникальный id.
Таким же образом должны быть реализованы сервисы, предоставляющие информацию о культурах и какой фермер владеет ими.
Имеем единственную конечную точку, которая отвечает за все действия. В примере ниже представлена только одна конечная точка /farmers для всех операций таких как добавление, обновление, удаление. Базовые реализации имеют различные HTTP методы, которые правильно маршрутизируются для разных операций.
Постарайтесь избегать использования глаголов. Рекомендуется представлять операции внутри таких форматах как JSON, XML, RAML или использовать HTTP методы. Не используйте представленные ниже обозначения:
• /getFarmers
• /updateFarmers
• /deleteFarmers
• /getCrops
• /updateCrops
• /deleteCrops
2. Множественное число
Используйте множественное число для названия своих REST сервисов. Это еще одна горячая тема для обсуждений среди REST дизайнеров – выбор между единственными или множественными формами существительных для обозначения сервисов.
Примечание:
Хотя я упоминаю, что использование множественного числа является best practice, по какой-то причине, если вы придерживаетесь единственного числа, то придерживайтесь этого во всех своих сервисах. Не смешивайте использование множественного и единственного чисел. Поэтому я и не говорю здесь про bad practice, а просто говорю, что это не рекомендуется. Пожалуйста, решайте сами, что лучше подходит для вашего приложения.
3. Документация
Документирование программного обеспечения является общей практикой для всех разработчиков. Этой практики стоит придерживаться и при реализации REST приложений. Если писать полезную документацию, то она поможет другим разработчикам понять ваш код.
Наиболее распространенным способом документирования REST приложений – это документация с перечисленными в ней конечными точками, и описывающая список операций для каждой из них. Есть множество инструментов, которые позволяют сделать это автоматически.
Ниже представлены приложения, которые помогают документировать REST сервисы:
Пожалуйста, поделитесь своим опытом документирования ваших приложений в комментариях.
4. Версия вашего приложения
Любое программное обеспечение развивается с течением времени. Это может потребовать различных версий для всех существенных изменений в приложении. Когда дело доходит до версии REST приложения, то оно становится одной из самых обсуждаемых тем среди сообщества разработчиков REST.
Существует два общих способа для управления версиями REST приложений:
1. URI версии.
2. Мультимедиа версии.
Ниже приведены основные недостатки способа создания версий с использованием URI:
Пример информации в заголовке:
GET /account/5555 HTTP/1.1
Accept: application/vnd.farmers.v1+json
HTTP/1.1 200 OK
Content-Type: application/vnd.farmers.v1+json
В мультимедийном подходе управления версиями клиент имеет возможность выбрать, какую версию запрашивать с сервера. Этот способ выглядит предпочтительней, чем подход с URI, но сложность возникает при кэшировании запросов с различными версиями, которые передаются через заголовок. Говоря простыми словами, когда клиент кэширует на основе URI, это просто, но, кэширование с ключом в качестве мультимедийного типа добавляет сложности.
5. Пагинация
Отправка большого объема данных через HTTP не очень хорошая идея. Безусловно, возникнут проблемы с производительностью, поскольку сериализация больших объектов JSON станет дорогостоящей. Best practice является разбиение результатов на части, а не отправка всех записей сразу. Предоставьте возможность разбивать результаты на странице с помощью предыдущих или следующих ссылок.
Если вы используете пагинацию в вашем приложении, одним из хороших способов указать ссылку на пагинацию является использование опции Link HTTP заголовка.
Следующая ссылка будет полезной для вас.
6. Использование SSL
SSL должен быть! Вы всегда должны применять SSL для своего REST приложения. Доступ к вашему приложения будет осуществляется из любой точки мира, и нет никакой гарантии, что к нему будет обеспечен безопасный доступ. С ростом числа инцидентов с киберпреступностью мы обязательно должны обеспечить безопасность своему приложению.
Стандартные протоколы проверки аутентификации облегчают работу по защите вашего приложения. Не используйте базовый механизм аутентификации. Используйте Oauth1.Oa или Oaurh2 для лучшей безопасности ваших сервисов. Я бы рекомендовал Oauth2 лично из-за его новейших функций.
7. HTTP методы
Проектирование операций на HTTP методы становится легче, когда вы знаете характеристики всех методов HTTP. В одном из предыдущих разделов этой статьи я настаивал на использовании HTTP методов для операций вместо написания различных наименований сервисов для каждой операции. В этом разделе в основном рассматривается поведение каждого HTTP метода.
Ниже представлены две характеристики, которые должны быть определены перед использованием HTTP метода:
REST HTTP методы
Ниже приведен краткий обзор каждого метода и рекомендации по их использованию:
8. Эффективное использование кодов ответов HTTP
HTTP определяет различные коды ответов для указания клиенту различной информации об операциях. Ваше REST приложение могло бы эффективно использовать все доступные HTTP-коды, чтобы помочь клиенту правильно настроить ответ. Далее представлен список кодов ответов HTTP:
Резюме
Надеюсь, эта статья будет полезна для понимания того, как создать свой REST API. Здесь представлены best practices, собранные на основе моего опыта и обсуждения с друзьями, которые работали над приложениями веб-служб REST.
Если вы много работали над дизайном REST API, и, если вы чувствуете, что эта статья не имеет для вас никакого смысла, я рад услышать ваши отзывы. Я хотел бы продолжить обновление этого обсуждения с помощью более проверенных методов разработки лучшего API для вашего приложения.
Хорошего прочтения. Спасибо за посещение моего блога.
Введение в REST API — RESTful веб-сервисы
Эта статья начинает серию постов о разработке REST API:
Intro to RESTful Web Services
REST означает REpresentational State Transfer (Википедия: «передача состояния представления»). Это популярный архитектурный подход для создания 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 — универсальный идентификатор ресурса. Например:
REST и Ресурсы
Важно отметить, что с REST вам нужно думать о приложении с точки зрения ресурсов:
Определите, какие ресурсы вы хотите открыть для внешнего мира
Используйте глаголы, уже определенные протоколом HTTP, для выполнения операций с этими ресурсами.
Вот как обычно реализуется служба REST:
Компоненты HTTP
HTTP определяет следующую структуру запроса:
Методы HTTP-запроса
Метод, используемый в HTTP-запросе, указывает, какое действие вы хотите выполнить с этим запросом. Важные примеры:
Код статуса ответа HTTP
Код состояния всегда присутствует в ответе HTTP. Типичные примеры:
Резюме
В статье приведен на верхнем уровне обзор архитектурного стиля REST. Подчеркивается тот факт, что HTTP является основным строительным блоком REST сервисов. HTTP — это протокол, который используется для определения структуры запросов и ответов браузера. Мы видели, что HTTP имеет дело главным образом с ресурсами, доступными на веб-серверах. Ресурсы идентифицируются с помощью URI, а операции над этими ресурсами выполняются с использованием глаголов, определенных протоколом HTTP.
Наконец, мы рассмотрели, как службы REST наилучшим образом используют функции, предлагаемые HTTP, для предоставления ресурсов внешнему миру. REST не накладывает никаких ограничений на форматы представления ресурсов или на определение сервиса.
REST API: что это такое простыми словами, примеры запросов, варианты использования сервиса, методы
В этой статье мы разберем оболочку REST API, расскажем, что это такое простыми словами, как работает система.
Так называется способ взаимодействия и обмена данными сервера. Большинство крупных компаний разрабатывают этот интерфейс для внутреннего использования или для своих клиентов. Подобная технология способна обеспечить сообщение между двумя системами. Сейчас этот подход сумел вытеснить практически все остальные, включая дизайны, которые были основаны на SOAP.
Что такое REST API
Это английская аббревиатура, которая расшифровывается и переводится как передача состояния представления. Web-службы, которые пользуются системой Representational State Transfer, применяют термин RESTful. Отличие этого архитектурного стиля от других состоит в том, что у него нет единого стандарта, однако при этом допустимо использовать XML, HTTP, JSON и URL.
Representational State Transfer разработали еще в 2000 году, но с того момента он очень развился и сейчас стал одним из самых популярных, отодвинув на задний план аналогичные.
Чтобы объяснить суть Restful API для чайников, можно представить калькулятор на любом компьютере. Когда мы нажимаем на кнопки, желая получить расчеты, также начинают действовать и скрытые функции, которые в итоге и помогают получить результат. А когда сервис получает ответ, он выводит его на экран в виде готовой цифры в графическом интерфейсе.
Здесь архитектура работает аналогичным образом. При нажатии на кнопку выполняются разные операции по обработке и передаче информации. Они могут не просто получать данные из одной сети, а способны вызывать и обращаться к удаленным серверам, чтобы взять нужное у них.
В качестве примера стоит привести кнопку Facebook, которая умеет задействовать соцсеть, или видео на Youtube, его тоже запускает веб-версия API.
Как работает
В первую очередь стоит разобраться, как действует подход:
Суть работы алгоритма заключается в паре действий, в зависимости от типа запроса. От работы сервера зависит функционал и способности архитектуры. Есть 4 основных вида в отношении информации:
В качестве пакета обычно отправляется JSON массив на указанный конкретный URL. Там срабатывает так называемая функция, а в зависимости от уже отправленных данных и текущего запроса начинается определенное действие. При этом не имеет значения, с какого устройства выслана информация — мобильное приложение или браузер компьютера.
Что такое API
По сути, это интерфейс программирования, который обладает следующими признаками:
Таким образом, это своеобразная созданная человеком архитектура, которая разработана с помощью ограничений и расширений. Если их использовать, то мы получаем стиль, который оптимизирован под заданные цели.
В его задачи входит представлять состояние передачи:
Протокол по типу концентрированного REST API, работающий по HTTP равно качественным веб-сервисам
Речь идет о веб-приложении, которое представляет ресурсы, включающие в себя разные интерфейсы, в формате, подходящем для других компьютеров.
Те варианты, которые применяются для транслирования, тоже можно учитывать как «веб-сервисы». Клиент, который пользуется этим, способен запросить все что угодно, а сервер ему отвечает и предоставляет результаты. При этом задействуется любой удобный язык программирования или подходящие платформы.
Это вообще лучшая часть всего созданного в компьютерном мире. Так как подобные веб-сервисы не зависят от языков, то могут совмещаться с самыми разными системами. Когда API документируется, то неважно, чем пользовались разработчики при его создании — Ruby это был, Java или Python или что-то принципиально другое. Все запросы высылаются через один и тот же HTTP, решения приходят таким же способом.
Дело в том, что этот протокол используется именно для реализации передачи, это своеобразный шаблон. Сервер способен говорить на любом языке программирования, информацию он анализирует по-своему, при этом сам не находится в зависимости от них, поэтому приходящая и уходящая информация схожа.
SOAP стоит отнести к предкам интерфейсов по типу REST API
Еще перед тем, как прикладное программирование нового поколения стало популярным и везде используемым, у него был аналог — SOAP. Он был максимально распространен. А чтобы понять разницу между этим интерфейсами, стоит разобраться в истоках.
SOAP — это протокол, который работает по заранее определенному стандарту. Ему для работы требуется XML, это определит формат, в котором будут отражаться входящие и исходящие запросы. Так как это стандартная вещь, подвид можно определить, если использовать файл WSDL — он помогает расшифровывать язык, на котором пишут веб-службы. Он определяет, есть ли атрибуты или какие-то расширенные элементы в передающихся сообщениях. Это машиночитаемая часть функционирования сети, поэтому пользуются им только сервера, которые действуют и общаются, чтобы облегчить связь.
Все сообщения внутри SOAP собираются в своеобразные «конвертики», в которых есть заголовок и основное тело. Все это «пакуется» при помощи заранее сформированной схемы по принципу XML.
Основная проблема этой системы в том, что формат, который используется для передачи, излишне тяжелый. Это вызывает серьезные проблемы в выполняемых сценариях на мобильных устройствах, задерживает загрузку, делает слишком медленной обработку. Там, где пропускная способность очень важна, эту схему использовать нецелесообразно. Это одна из причин, по которой был придуман и создан rest-сервис.
Рекомендации по REST API — примеры проектирования веб-сервисов на Java и Spring
Это последняя статья из серии статей про REST API:
При разработке хорошего REST API важно иметь хорошие микросервисы.
Как вы разрабатываете свой REST API? Каковы лучшие практики?
Вы изучите:
Используйте Consumer First подход
Кто будет пользоваться вашим сервисом? Потребитель услуг.
Вы смотрите на сервис с точки зрения потребителя?
Всякий раз, когда у вас проходит обсуждение или ревью сервиса, ставьте требования потребителя на первое место.
Используйте Contract First подход
Что такое контракт?
Создатель веб-сервиса считается поставщиком сервиса. Приложение, которое использует веб-сервис, является потребителем сервиса. Контракт — это соглашение между поставщиком и потребителем об услуге.
Чтобы правильно использовать услугу, потребитель сервиса должен полностью понимать договор. Контракт включает в себя детали многих аспектов обслуживания, таких как:
При contract first подходе вы сначала определяете контракт на обслуживание, а затем только внедряете сервис.
Contract First с WSDL
Например, когда вы определяете веб-службы SOAP, вы используете WSDL для определения договора.
WSDL определяет, каковы конечные точки службы, операции, которые вы публикуете, и структуры запроса и ответа.
Contract First с Swagger / Open API
Когда вы используете RESTful веб-сервисы, Swagger — это популярный инструмент для документирования ваших веб-сервисов.
Swagger позволяет вам определить, какие ресурсы вы предоставляете в рамках своего API. Он включает в себя детали каждой операции, например, использует ли он XML, JSON или оба. Схема ответов также присутствует там.
Он также дает подробную информацию о кодах ответов, которые он поддерживает. Вы также можете увидеть, что этот конкретный ресурс, /jpa/users:
поддерживает операцию GET. Фактически также поддерживает операцию POST:
Схема ответа, если этот ресурс доступен, будет:
Определение объекта User присутствует в договоре Swagger как:
Он включает в себя атрибуты: birthDate, id, name и массив сообщений posts. Некоторые поля также включают в себя поле описания внутри них.
При contract first подходе перед внедрением сервиса вы вручную или с помощью приложения создаете такое определение, какое создал Swagger.
Преимущества подхода Contract First
Используя contract first подход, вы думаете о своих потребителях и о том, как они могут использовать эту услугу. Вы изначально не беспокоитесь о деталях реализации.
Если на раннем этапе вы придаете большое значение внедрению, технические подробности проникают в определение вашего сервиса.
Определите организационные стандарты для REST API
Важным ориентиром для ваших организационных стандартов является YARAS.
YARAS означает Yet Another RESTful API Standard (еще один стандарт RESTful API). YARAS предоставляет стандарты, руководства и соглашения, которые необходимо соблюдать при разработке RESTful веб-сервисов. Он дает рекомендации для следующих вещей:
Единый подход к разработке сервисов
Вам нужно решить множество сложных проблем, прежде чем приступить к проектированию RESTful веб-сервисов. Все перечисленное выше, необходимо выяснить.
Руководство вашей организация не захочет, чтобы команды, которые занимаются различными ресурсами, разные подходы к этим вещам.
Например, нежелательно, чтобы Команда-A организовывала версионность на основе параметров запроса, а Команда-B использовало версионность на основе URI.
Поэтому важно, чтобы у вас были четко определенные организационные стандарты для подхода к RESTful веб-сервисАМ.
Кастомизация YARAS ПОД организационные нужды
Хорошая вещь в YARAS — это то, что он может быть настроен для удовлетворения потребностей, специфичных для организации. Например, вы можете:
Выбор стандартного общеорганизационного REST API фреймвока
Типичными фреймвоками, которые используются для создания веб-сервисов RESTful в мире Java, являются Spring MVC, Spring REST и JAX-RS.
Если вы создадите специфичную для организации фреймвок/архетип/эталонное приложение, придерживающееся общих стандартов организации, поверх предпочтительной REST API платформы, это позволит командам легко придерживаться общих стандартов.
Типичные особенности включают в себя:
Децентрализованное управление REST API
Создайте группу экспертов из команд, создающих REST API, и сформируйте команду управления. Команда несет ответственность за
Широкое использование HTTP
Всякий раз, когда вы думаете о веб-сервисах RESTful, думайте о HTTP.
HTTP имеет все функции, которые помогут вам создавать отличные веб-сервисы.
Используйте правильные методы HTTP-запросов
Подумайте о методах HTTP-запросов, которые вам нужно использовать. Когда вы думаете о реализации какой-либо операции, определите ресурс, на котором она должна быть выполнена, а затем найдите соответствующий метод HTTP-запроса. Вы извлекаете детали, создаете что-то, обновляете что-то существующее или удаляете существующее?
Использование HTTP методов:
Используйте соответствующий статус ответа HTTP
При выполнении операции убедитесь, что вы вернули правильный статус ответа.
Например, когда конкретный ресурс не найден, не выбрасывайте исключение сервера. Вместо этого отправьте соответствующий код ответа в ответном сообщении, например 404.
Если на самом деле существует исключение сервера, отправьте обратно код 500.
В случае ошибки проверки отправьте код для неверного запроса.
Фокус на представление
Каждый ресурс может иметь несколько представлений — в формате XML или JSON. Потребитель услуг может выбрать представление по своему выбору.
Сервис возвращает 3 элемента users, когда мы отправляем запрос GET. В этом случае мы получаем JSON-представление ресурса /users.
Когда потребитель не указывает предпочтительное представление, мы используем JSON.
Потребитель может отправить заголовок Accept, чтобы указать представление.
Тело ответа теперь имеет содержимое XML:
Используйте множественное число
Всегда используйте множественное число, когда вы именуете ресурсы.
Давайте посмотрим на простой пример. Предположим, у нас есть сервис, который размещает ресурс пользователя. Ниже описано, как получить к ним доступ:
Создать хорошую документацию
Потребители должны понимать, как наилучшим образом использовать сервис, и лучший способ помочь им — создавать хорошую документацию.
Веб-сервисы SOAP могут использовать функциональность WSDL, в то время как RESTful веб-сервисы имеют опции Swagger (теперь стандарт документации Open API).
Выбор формата — это только одна часть создания хорошей документации. Что также важно, так это предоставление нужного количества информации, чтобы помочь потребителю.
Документация должна быть полной и включать следующие пункты:
Создать общий портал документации REST API
Полезно было бы иметь общий портал документации REST API для всей организации. Взгляните на один такой портал:
Такой портал объединяет все ресурсы, имеющиеся в организации. Наличие пользовательского интерфейса, такого как Swagger UI, будет иметь свои дополнительные преимущества. Используя Swagger UI, вы можете посмотреть документацию более подробно:
Это может быть использовано даже нетехническими пользователями. Информация, предоставляемая здесь, включает в себя:
Поддержка версий
Управление версиями влечет за собой большую сложность для веб-службы. Поддерживать несколько разных версий одного и того же веб-сервиса очень сложно. Старайтесь избегать этого, когда это возможно.
Однако в определенных сценариях управление версиями неизбежно.
Давайте начнем с рассмотрения примера службы. Предположим, что мы изначально определили службу, имеющую класс PersonV1, следующим образом:
Эта версия класса не учитывает, что у имени может быть много подразделов, таких как имя и фамилия. Посмотрите это:
Вторая версия исходного класса была обновлена, чтобы исправить эту аномалию:
Мы не можем сразу перенести весь сервис для использования PersonV2! Там могут быть другие потребители, которые ожидают ответов в формате PersonV1.
Вот где требуется управление версиями.
Давайте теперь посмотрим на варианты, которые мы имеем для управления версиями этих двух ресурсов.
Использование разных URI
У нас есть один вариант — использовать разные URI для этих разных ресурсов. В приведенном ниже коде экзамена мы используем URI v1/person и v2/person для их различения:
Если вы выполняете запрос GET для ресурса v1/person:
Вы получите информацию, соответствующую v1. Для другого ресурса:
Использование параметра запроса
Второй метод управления версиями использует параметр запроса:
В URI /person/param, если мы отправляем параметр с версией=1, мы возвращаем ресурс типа PersonV1:
Для того же URI параметр с version=2 возвращает ресурс типа PersonV2:
Этот метод называется управлением версиями с помощью параметров запроса.
Использование Header (заголовка)
Другим способом вы можете сделать это управление версиями, указав заголовок. Здесь мы используем заголовок с именем X-API-VERSION и пометили URI как /person/header. Когда значение заголовка равно 1, возвращается ресурс типа PersonV1:
Когда его значение равно 2, ресурс типа PersonV2 извлекается:
Мы используем атрибут в заголовке запроса, чтобы выполнить управление версиями для нас.
Использование Accept Header
Последний метод для создания версий использует Accept Header. Если потребитель включает первую информацию о версиях в Accept Header запроса GET, возвращается следующий ресурс:
В противном случае возвращается ресурс типа PersonV2:
Этот способ управления версией называется Accept Header Versioning или Media Type Versioning, поскольку MIME-типы обычно являются содержимым заголовка Accept.
Сравнение методов управления версиями
До сих пор мы видели четыре типа методов версиями:
Вам необходимо оценить эти четыре варианта в соответствии с вашими конкретными потребностями. Есть ряд важных факторов, которые следует учитывать:
Подумайте об обработке ошибок
Когда потребитель отправляет запрос в службу, важно, чтобы он получил правильный ответ. Всякий раз, когда что-то идет не так, важно отправить соответствующий ответ.
Когда потребитель запрашивает несуществующий ресурс
Если мы отправим запрос GET для поиска существующего пользователя, мы получим следующий ответ:
Если вы ищете несуществующего пользователя:
То, что вы получите, это статус 404 Not Found. Это хорошая обработка ошибок, поскольку она правильно определяет, что ресурс не найден, и не возвращает ошибку сервера.
Давайте теперь отправим запрос GET на несуществующий URI:
Как видидите, вы получаете статусы ответа 404 Not Found. Неправильный URL указывает на несуществующий ресурс.
Важные статусы ответа
Сведения об ошибках в теле ответа
Это помогает, если у вас есть стандартная структура исключений при разработке вашего сервиса.
Для конкретных ошибок конкретные структуры ответа могут быть возвращены потребителю, и это может быть стандартом во всей организации. Убедитесь, что ответ об ошибке также читается потребителям, без путаницы.
Использование Swagger или Open API Documentation
Swagger обеспечивает один из самых популярных форматов документации для веб-сервисов RESTful. Сегодня он поддерживается различными организациями и используется в большом количестве услуг. Здесь мы рассмотрим два основных аспекта Swagger:
Swagger Документация
Посмотрите на следующий Swagger JSON:
Когда вы посмотрите на документацию по Swagger, вы сможете быстро определить имеющиеся ресурсы, поддерживаемые операции и операции, относящиеся к каждому ресурсу:
Ресурс /users поддерживает операции GET и POST. Для GET вы можете увидеть поддерживаемые типы запросов и ответов. Вы также видите различные типы ответов:
Обратите внимание, что для ответа 200 схема также упоминается как массив User. User является частью раздела definitions (определения) в нижней части документа:
Swagger полностью независим от технологии, которую вы используете для реализации RESTful веб-сервиса. О все работает на основе JSON.
Представляем Swagger UI
Swagger UI — отличный пользовательский интерфейс, который очень полезен для визуализации документации Swagger для веб-службы RESTful. Посмотрите на скриншот ниже:
Обратите внимание, что мы выбрали конкретную версию веб-сервиса для просмотра его документации. Вот тот же экран более подробно:
Когда мы заходим на домашнюю страницу, она описывает перечисленные ресурсы:
Также можно увидеть набор операций, поддерживаемых для URL ресурсов:
Когда вы нажимаете на операцию GET определенного ресурса, вы получаете его детали:
Вы можете увидеть, что схема модели описана визуально. Атрибуты birthDate, id, links, name и posts также отображаются. Вы также можете выполнить пример запроса и просмотреть ответ:
Использование инструментов Swagger (стандарт Open API)
Самое замечательное в Swagger — множество инструментов, доступных вокруг него. Взгляните на следующий сервис, который мы использовали ранее, чтобы объяснить управление версиями: Вот посмотрите на автоматически сгенерированную документацию для этого сервиса:
В Swagger есть поддержка как подхода contract-first, так и подхода code-first.
По этому вопросу имеется авторское видео.
Резюме
В этой статье мы рассмотрели лучшие практики создания и проектирования RESTful веб-сервисов.