Общие сведения о создании конечных точек
все взаимодействия со службой Windows Communication Foundation (WCF) осуществляется через конечные точки службы. Конечные точки предоставляют клиентам доступ к функциональным возможностям, предлагаемым службой WCF. В данном разделе приводится описание структуры конечной точки и способов определения конечной точки в конфигурации и в коде.
Структура конечной точки
Каждая конечная точка содержит адрес, показывающий, где можно найти конечную точку, привязку, показывающую, как клиент может связаться с конечной точкой, и контракт, определяющий доступные методы.
Адрес. Адрес однозначно определяет конечную точку и указывает потенциальным потребителям на место расположения службы. Он представлен в объектной модели WCF EndpointAddress адресом, который содержит универсальный код ресурса (URI) и свойства адреса, включающие удостоверение, некоторые элементы языка описания веб-служб (WSDL) и коллекцию необязательных заголовков. Необязательные заголовки содержат более подробную информацию для идентификации конечной точки и взаимодействия с ней. Дополнительные сведения см. в разделе Указание адреса конечной точки.
Привязка. Привязка задает способ связи клиента с конечной точкой. Привязка задает способ связи конечной точки с внешним миром, включая используемый транспортный протокол (например, TCP или HTTP), используемое кодирование сообщений (например, текстовое или двоичное) и необходимые требования безопасности (например, безопасность сообщений SSL или SOAP). Дополнительные сведения см. в разделе Использование привязок для настройки служб и клиентов.
Контракт службы. Контракт службы показывает, какие функциональные возможности предоставляет клиенту конечная точка. Контракт указывает операции, которые может вызвать клиент, форму сообщения и тип входных параметров или данных, требуемых для вызова операции, а также тип обработки или ответного сообщения, которые может ожидать клиент. Три базовых типа контрактов соответствуют базовым шаблонам обмена сообщениями (MEP): датаграмма (односторонняя связь), запрос-ответ и дуплексная связь (двунаправленная). Контракт службы также может задействовать контракты данных и контракты сообщений, чтобы при обращении требовались определенные типы данных и форматы сообщений. Дополнительные сведения о том, как определить контракт службы, см. в разделе проектирование контрактов служб. Обратите внимание, что клиент также может потребоваться для реализации определяемого службой контракта, называемого контрактом обратного вызова, чтобы получить сообщения от службы в дуплексном шаблоне обмена сообщениями. Дополнительные сведения см. в разделе Дуплексные службы.
Конечную точку службы можно задать императивно с помощью кода или декларативно с помощью конфигурации. Если конечные точки не заданы, то среда выполнения предоставляет конечные точки по умолчанию, добавляя одну конечную точку по умолчанию для каждого базового адреса в каждом контракте службы, реализованном в службе. Как правило, определять конечные точки в коде непрактично, поскольку привязки и адреса для развернутой службы чаще всего отличаются от привязок и адресов, используемых в процессе разработки службы. Обычно более целесообразно задать конечные точки службы в конфигурации, а не в коде. Если не указывать привязку и адрес в коде, их можно изменять без повторной компиляции и повторного развертывания приложения.
При добавлении конечной точки службы, выполняющей олицетворение, необходимо использовать либо один из методов AddServiceEndpoint, либо метод GetContract(Type, Type), чтобы правильно загрузить контракт в новый объект ServiceDescription.
Определение конечных точек в коде
В следующем примере показано, как задать конечную точку в коде.
Укажите адрес конечной точки http://localhost:8000/Echo для службы.
Настройте службу Echo с помощью привязки WSHttpBinding.
Узел службы создается с базовым адресом, а затем остальная часть адреса, относящаяся к базовому адресу, задается как часть конечной точки. Такое секционирование адреса обеспечивает более удобное определение нескольких конечных точек для служб в узле.
Свойства объекта ServiceDescription в приложении службы нельзя изменять после вызова метода OnOpening для объекта ServiceHostBase. Некоторые члены, такие как свойство Credentials и методы AddServiceEndpoint для объектов ServiceHostBase и ServiceHost, создают исключение, если их изменить на этом этапе. Другие члены можно изменять без появления исключения, но результат при этом будет неопределенным.
Аналогично, на стороне клиента нельзя изменять значения ServiceEndpoint после вызова метода OnOpening для объекта ChannelFactory. Если после этого изменить свойство Credentials, создается исключение. Изменение других значений описания клиента происходит без ошибок, но результат изменения в этом случае является неопределенным.
Как для службы, так и для клиента, рекомендуется изменять описание до вызова метода Open.
Определение конечных точек в конфигурации
При создании приложения часто нужно отложить решения для администратора, который выполняет развертывание приложения. Например, часто невозможно узнать заранее, каким будет адрес службы (универсальный код ресурса (URI)). Вместо жестко запрограммированного адреса желательно разрешить администратору ввести его после создания службы. Такая гибкость достигается благодаря конфигурации. Дополнительные сведения см. в разделе Настройка служб.
Для быстрого создания файлов конфигурации используйте средство служебной программы метаданных ServiceModel (Svcutil.exe) с /config: [, ] параметром filename имя_файла.
Использование конечных точек по умолчанию
Если конечные точки не заданы в коде или в конфигурации, то среда выполнения создает конечные точки по умолчанию, добавляя одну конечную точку по умолчанию для каждого базового адреса в каждом контракте службы, реализованном в службе. Базовый адрес можно указывать в коде или в конфигурации, а конечные точки по умолчанию добавляются, когда вызывается метод Open() в объекте ServiceHost. Этот пример аналогичен примеру из предыдущего раздела, однако конечные точки не указаны, и поэтому добавляются конечные точки по умолчанию.
Если конечные точки предоставляются явно, то конечные точки по умолчанию можно добавить, вызвав метод AddDefaultEndpoints класса ServiceHost перед вызовом Open. Дополнительные сведения о конечных точках по умолчанию см. в разделе упрощенная конфигурация и упрощенная конфигурация для служб WCF.
Тестирование API
Введение: Что такое API
В широком смысле слова API (Application Programming Interface) это метод который приложение предоставляет внешним пользователям для коммуникации с ним. Обычно через Интернет.
Это может быть взаимодействие с сервером приложения на смартфоне, между компьютерами или другими устройствами.
API применяются там где невозможна или нежелательна непосредственная интеграция с исходным приложением, то есть практически везде.
Крупные интернет-компании обычно предоставляют (платно или бесплатно) доступ к API своих сервисов.
Где применяют API
Сейчас будет несколько абстрактных примеров просто для понимания сути.
Конкретные примеры работы с API я разбираю в учебнике
Пример №1:
Если Вы хотите разместить на своём сайте яндекс-карты Вам не нужно устанавливать программы от Яндекса, достаточно послать несколько запросов и Яндекс передаст необходимую информацию.
Пример №2:
Предположим, что Вы создали сайт vk2.com. Вы хотите, чтобы вебмастера могли добавить на свои сайты возможность комментировать записи используя учётную запись vk2, но раскрывать или раздавать свой код не хотите.
Чтобы обойти эту проблему Вы выкладываете в публичном доступе правила, по которым вебмастера могут обращаться к vk2, чтобы получить комментарии.
Формат этих сообщений это обычно либо JSON либо XML. О них мы поговорим позже.
Повторим для закрепления сути: Смысл в том, что сайт написанный на любом языке, поддерживающем HTTP запросы, не посылает на сервер никаких PHP/C/Python команд, а общается ним с помощью запросов, описанных в API.
Если вам интересен реальный пример работы с API рекомендую статью Работа с API GitHub
Endpoint
Адрес, на который посылаются сообщения называется Endpoint.
Обычно это URL (например, название сайта) и порт. Если я хочу создать веб сервис на порту 8080 Endpoint будет выглядеть так:
Если моему Web сервису нужно будет отвечать на различные сообщения я создам сразу несколько URL (interfaces) по которым к сервису можно будет обратиться. Например
https://andreyolegovich.ru:8080 /resource1/status
https://andreyolegovich.ru:8080 /resource1/getserviceInfo
https://andreyolegovich.ru:8080 /resource1/putID
http://andreyolegovich.ru:8080 /resource1/eventslist
https://andreyolegovich.ru:8080 /resource2/putID
…
Как видите у моих эндпойнтов (Enpoints) различные окончания. Такое окончание в Endpoint называются Resource, а начало Base URL.
Такое определение Endpoint и Resource используется, например, в SOAP UI для RESTful интерфейсов
Endpoint = Base URL + Resource
Понятие Endpoint может использоваться в более широком смысле. Можно сказать, что какой-то определённый роутер или компьютер является Endpoint. Например, в понятии Endpoint Management под Endpoint имеют в виду конечное устройство. Обычно это понятно из контекста.
Также следует обратить внимание на то, что понятие Endpoint выходит за рамки RESTful и может использовать как в SOAP так и в других протоколах.
Термин Resource также связан с RESTful, но в более широком смысле может означать что-то другое.
На программистском сленге Endpoint иногда называют ручкой.
Спецификация
После того все эти интерфейсы созданы, их необходимо описать. Нужен документ из которого будет понятно
Этот документ должен быть доступен программистам с обеих сторон, иначе они просто не смогут договориться и реализовать работающий Web сервис.
HTTP методы
Вернёмся к первому пункту списка, а именно к тому, что такое методы.
В протоколе HTTP предусмотрено несколько способов отправить запрос на один и тот же Endpoint.
Про их свойства можно почитать здесь.
Когда мы знаем какие методы с какими Enpoint можно использовать составить запросы не составит труда.
GET http://andreyolegovich.ru:8080 /resource1/status
GET http://andreyolegovich.ru:8080 /resource1/getserviceInfo
PUT http://andreyolegovich.ru:8080 /resource1/putID
GET http://andreyolegovich.ru:8080 /resource1/eventslist
POST http://andreyolegovich.ru:8080 /resource1/eventslist
PUT http://andreyolegovich.ru:8080 /resource2/putID
…
Таким образом простейший запрос состоит из метода и Enpoint
Request = Method + Endpoint
Пример API
Чтобы узнать количество велосипедистов в городе нужно отправить GET запрос на https://topbicycle.ru:/bicyclists/$город
GET https://topbicycle.ru /bicyclists/helsinki
Получив такой запрос сайт вернёт число велосипедистов в Хельсинки.
Попробуйте вставить эту строку в браузер.
Это очень простые уроки для самых начинающих. Буду рад любым отзывам и предложениям в комментариях.
Тестирование API без документации
Если Вам по какой-то причине предстоит проделать эту неблагодарную работу, определетесь, насколько всё плохо. Какая у Вас есть информация об объекте тестирования.
Известно ли какие порты для Вас открыты? Знаете ли Вы нужные endpoints?
Сканирование портов
Перебор запросов
Если Вам известен нужный порт и соответствующий endopoint переберите все возможные HTTP методы. Начните с наиболее очевидных:
В худшем случае, когда ни порт ни endpoints неизвестны Вам, скорее всего придётся перебирать все открытые порты и генерировать endpoints, которые подходят по смыслу.
Разработчики обычно не особо заморачиваются и закладывают минимально-необходиму информацию. Так что включите воображение и попробуйте придумать endpoints опираясь на бизнес логику и принятые в Вашей компании стандарты.
Если ни endpoints ни бизнес логика Вам неизвестны, то у меня есть подозрение, что Вы тестируете API с не самыми хорошими намерениями.
Инструменты для тестирования
Существует множество инструментов для тестирования. Здесь Вы можете познакомиться с одними из самых популярных: Python и SOAP UI.
О работе с REST API на Python вы можете прочитать в статье «REST API с Python»
Kubernetes: что такое Endpoints
Практически все знают, что такое Kubernetes Service, но не все могут быть в курсе, что такое Endpoint, так как обычно он работает “за кулисами”, и мы его не видим, аналогично тому, как мы пользуемся Deployment, но редко видим ReplicaSet-ы.
Kubernetes Service
Как только в кластере появляется новый под, лейблы которого совпадают с селектором Сервиса, в данном примере app=MyApp – Service начнёт роутить трафик на него.
Реализуется это путём добавления IP-адреса пода в список Endpoints, который используется Сервисом.
Создадим простейший пример:
Kubernetes Endpoints
Теперь рассмотрим этот Сервис детальнее:
В конце мы собственно и видим Endpoints этого сервиса – IP-адрес пода.
А теперь проверим ендпоинты, которые являются отдельными объектами API-сервера – Endpoints, и с которыми можно работать так же, как с Services и Pods:
Если мы добавим ещё один под с той же лейблой, в Deployment или просто опишем вторым объектом – он будет добавлен в этот же Ендпоинт:
И проверяем ендпоинт:
Тут у нас остался старый под 10.21.56.143:80, и появилось два новых, которые указаны в replicas нашего деплоймента.
Custom Endpoint
Кроме ендпоинтов подов, мы можем создать кастомный ендпоинт, который будет слать трафик на любой ресурс.
К примеру, опишем такой сервис:
Автоматизация Для Самых Маленьких. Заметки. RESTful API
Эта статья — одна из обещанных коротких заметок по ходу цикла статей Автоматизация Для Самых Маленьких.
Поскольку основным способом взаимодействия с IPAM-системой будет RESTful API, я решил рассказать о нём отдельно.
Воздаю хвалы архитекторам современного мира — у нас есть стандартизированные интерфейсы. Да их много — это минус, но они есть — это плюс.
Эти интерфейсы взаимодействия обрели имя API — Application Programming Interface.
Одним из таких интерфейсов является RESTful API, который и используется для работы с NetBox.
Если очень просто, то API даёт клиенту набор инструментов, через которые тот может управлять сервером. А клиентом может выступать по сути что угодно: веб-браузер, командная консоль, разработанное производителем приложение, или вообще любое другое приложение, у которого есть доступ к API.
Например, в случае NetBox, добавить новое устройство в него можно следующими способами: через веб-браузер, отправив curl’ом запрос в консоли, использовать Postman, обратиться к библиотеке requests в питоне, воспользоваться SDK pynetbox или перейти в Swagger.
Таким образом, один раз написав единый интерфейс, производитель навсегда освобождает себя от необходимости с каждым новым клиентом договариваться как его подключать (хотя, это самую малость лукавство).
Содержание
REST, RESTful, API
Ниже я дам очень упрощённое описание того, что такое REST.
Начнём с того, что RESTful API — это именно интерфейс взаимодействия, основанный на REST, в то время как сам REST (REpresentational State Transfer) — это набор ограничений, используемых для создания WEB-сервисов.
О каких именно ограничениях идёт речь, можно почитать в главе 5 диссертации Роя Филдинга Architectural Styles and the Design of Network-based Software Architectures. Мне же позвольте привести только три наиболее значимых (с моей точки зрения) из них:
А API, который предоставляют RESTful WEB-сервисы, называется RESTful API.
REST — не протокол, а, так называемый, стиль архитектуры (один из). Развиваемому вместе с HTTP Роем Филдингом, REST’у было предназначено использовать HTTP 1.1, в качестве транспорта.
Адрес назначения (или иным словом — объект, или ещё иным — эндпоинт) — это привычный нам URI.
Формат передаваемых данных — XML или JSON.
Для этой серии статей на linkmeup развёрнута read-only (для вас, дорогие, читатели) инсталляция NetBox: netbox.linkmeup.ru:45127.
На чтение права не требуются, но если хочется попробовать читать с токеном, то можно воспользоваться этим: API Token: 90a22967d0bc4bdcd8ca47ec490bbf0b0cb2d9c8.
Давайте интереса ради сделаем один запрос:
То есть утилитой curl мы делаем GET объекта по адресу netbox.linkmeup.ru:45127/api/dcim/devices/1/ с ответом в формате JSON и отступом в 4 пробела.
Или чуть более академически: GET возвращает типизированный объект devices, являющийся параметром объекта DCIM.
Этот запрос можете выполнить и вы — просто скопируйте себе в терминал.
URL, к которому мы обращаемся в запросе, называется Endpoint. В некотором смысле это конечный объект, с которым мы будем взаимодействовать.
Например, в случае netbox’а список всех endpoint’ов можно получить тут.
И ещё обратите внимание на знак / в конце URL — он обязателен.
Вот что мы получим в ответ:
Это JSON (как мы и просили), описывающий device с ID 1: как называется, с какой ролью, какой модели, где стоит итд.
Так будет выглядеть HTTP-запрос:
Так будет выглядеть ответ:
А теперь разберёмся, что же мы натворили.
Структура сообщений HTTP
HTTP-сообщение состоит из трёх частей, только первая из которых является обязательной.
Стартовая строка
Стартовые строки HTTP-запроса и ответа выглядят по-разному.
HTTP-Запрос
Метод определяет, какое действие клиент хочет совершить: получить данные, создать объект, обновить его, удалить.
URI — идентификатор ресурса, куда клиент обращается или иными словами путь к ресурсу/документу.
HTTP_VERSION — соответственно версия HTTP. На сегодняшний день для REST это всегда 1.1.
HTTP-Ответ
HTTP_VERSION — версия HTTP (1.1).
STATUS_CODE — три цифры кода состояния (200, 404, 502 итд)
REASON_PHRASE — Пояснение (OK, NOT FOUND, BAD GATEWAY итд)
Заголовки
В заголовках передаются параметры данной HTTP-транзакции.
Например, в примере выше в HTTP-запросе это были:
Тело HTTP-сообщения
Тело используется для передачи собственно данных.
В HTTP-ответе это может быть HTML-страничка, или в нашем случае JSON-объект.
Между заголовками и телом должна быть как минимум одна пустая строка.
При использовании метода GET в HTTP-запросе обычно никакого тела нет, потому что передавать нечего. Но тело есть в HTTP-ответе.
А вот например, при POST уже и в запросе будет тело. Давайте о методах и поговорим теперь.
Методы
Как вы уже поняли, для работы с WEB-сервисами HTTP использует методы. То же самое касается и RESTful API.
Возможные сценарии в реальной жизни описываются термином CRUD — Create, Read, Update, Delete.
Вот список наиболее популярных методов HTTP, реализующих CRUD:
Давайте на примере NetBox разберёмся с каждым из них.
HTTP GET
Это метод для получения информации.
Так, например, мы забираем список устройств:
Метод GET безопасный (safe), поскольку не меняет данные, а только запрашивает.
Он идемпотентный с той точки зрения, что один и тот же запрос всегда возвращает одинаковый результат (до тех пор, пока сами данные не поменялись).
На GET сервер возвращает сообщение с HTTP-кодом и телом ответа (response code и response body).
То есть если всё OK, то код ответа — 200 (OK).
Если URL не найден — 404 (NOT FOUND).
Если что-то не так с самим сервером или компонентами, это может быть 500 (SERVER ERROR) или 502 (BAD GATEWAY).
Все возможные коды ответов.
Тело возвращается в формате JSON или XML.
Давайте ещё пару примеров. Теперь мы запросим информацию по конкретному устройству по его имени.
Здесь, чтобы задать условия поиска в URI я ещё указал атритбут объекта (параметр name и его значение mlg-leaf-0). Как вы можете видеть, перед условием и после слэша идёт знак «?», а имя и значение разделяются знаком «=».
Так выглядит запрос.
Если нужно задать пару условий, то запрос будет выглядеть так:
Здесь мы запросили все устройства с ролью leaf, расположенные на сайте mlg.
То есть два условия отделяются друг от друга знаком «&».
Из любопытного и приятного — если через «&» задать два условия с одним именем, то между ними будет на самом деле не логическое «И», а логическое «ИЛИ».
То есть вот такой запрос и в самом деле вернёт два объекта: mlg-leaf-0 и mlg-spine-0
Попробуем обратиться к несуществующему URL.
HTTP POST
POST используется для создания нового объекта в наборе объектов. Или более сложным языком: для создания нового подчинённого ресурса.
Уточнение от arthuriantech:
Включая, но не ограничиваясь. Метод POST предназначен для передачи данных на сервер с целью дальнейшей обработки — он используется для любых действий, которые не нужно стандартизировать в рамках HTTP. До RFC 5789 он был единственным легальным способом вносить частичные изменения.
roy.gbiv.com/untangled/2009/it-is-okay-to-use-post
tools.ietf.org/html/rfc7231#section-4.3.3
То есть, если есть набор devices, то POST позволяет создать новый объект device внутри devices.
Выберем тот же Endpoint и с помощью POST создадим новое устройство.
Здесь уже появляется заголовок Authorization, содержащий токен, который авторизует запрос на запись, а после директивы -d расположен JSON с параметрами создаваемого устройства:
Запрос у вас не сработает, потому что Токен уже не валиден — не пытайтесь записать в NetBox.
В ответ приходит HTTP-ответ с кодом 201 (CREATED) и JSON’ом в теле сообщения, где сервер возвращает все параметры о созданном устройстве.
Теперь новым запросом с методом GET можно его увидеть в выдаче:
«q» в NetBox’е позволяет найти все объекты, содержащие в своём названии строку, идущую дальше.
POST, очевидно, не является ни безопасным, ни идемпотентным — он наверняка меняет данные, и дважды выполненный запрос приведёт или к созданию второго такого же объекта, или к ошибке.
HTTP PUT
Это метод для изменения существующего объекта. Endpoint для PUT выглядит иначе, чем для POST — в нём теперь содержится конкретный объект.
PUT может возвращать коды 201 или 200.
Важный момент с этим методом: нужно передавать все обязательные атрибуты, поскольку PUT замещает собой старый объект.
Поэтому, если например, просто попытаться добавить атрибут asset_tag нашему новому устройству, то получим ошибку:
Но если добавить недостающие поля, то всё сработает:
Обратите внимание на URL здесь — теперь он включает ID устройства, которое мы хотим менять (18).
HTTP PATCH
Этот метод используется для частичного изменения ресурса.
WAT? Спросите вы, а как же PUT?
PUT — изначально существовавший в стандарте метод, предполагающий полную замену изменяемого объекта. Соответственно в методе PUT, как я и писал выше, придётся указать даже те атрибуты объекта, которые не меняются.
А PATCH был добавлен позже и позволяет указать только те атрибуты, которые действительно меняются.
Здесь также в URL указан ID устройства, но для изменения только один атрибут serial.
HTTP DELETE
Очевидно, удаляет объект.
Метод DELETE идемпотентен с той точки зрения, что повторно выполненный запрос уже ничего не меняет в списке ресурсов (но вернёт код 404 (NOT FOUND).
Способы работы с RESTful API
Curl — это, конечно, очень удобно для доблестных воинов CLI, но есть инструменты получше.
Postman
Postman позволяет в графическом интерфейсе формировать запросы, выбирая методы, заголовки, тело, и отображает результат в удобочитаемом виде.
Кроме того запросы и URI можно сохранять и возвращаться к ним позже.
Так мы можем сделать GET:
Здесь указан Token в GET только для примера.
Postman служит только для работы с RESTful API.
Например, не пытайтесь через него отправить NETCONF XML, как это делал я на заре своей автоматизационной карьеры.
Один из приятных бонусов специфицированного API в том, что вы можете в Postman импортировать все эндпоинты и их методы как коллекцию.
Для этого в окне Import (File->Import) выберите Import From Link и вставьте в окно URL netbox.linkmeup.ru:45127/api/docs/?format=openapi.
Далее, всё, что только можно, вы найдёте в коллекциях.
Python+requests
Но даже через Postman вы, скорее всего, не будете управлять своими Production-системами. Наверняка, у вас будут внешние приложения, которые захотят без вашего участия взаимодействовать с ними.
Например, система генерации конфигурации захочет забрать список IP-интерфейсов из NetBox.
В Python есть чудесная библиотека requests, которая реализует работу через HTTP.
Пример запроса списка всех устройств:
Снова добавим новое устройство:
Python+NetBox SDK
В случае NetBox есть также Python SDK — Pynetbox, который представляет все Endpoint’ы NetBox в виде объекта и его атрибутов, делая за вас всю грязную работу по формированию URI и парсингу ответа, хотя и не бесплатно, конечно.
Например, сделаем то же, что и выше, использую pynetbox.
Список всех устройств:
Добавить новое устройство:
SWAGGER
За что ещё стоит поблагодарить ушедшее десятилетие, так это за спецификации API. Если вы перейдёте по этому пути, то попадёте в Swagger UI — документацию по API Netbox.
На этой странице перечислены все Endpoint’ы, методы работы с ними, возможные параметры и атрибуты и указано, какие из них обязательны. Кроме того описаны ожидаемые ответы.
На этой же странице можно выполнять интерактивные запросы, кликнув на Try it out.
По какой-от причине swagger в качестве Base URL берёт имя сервера без порта, поэтому функция Try it out не работает в моих примерах со Swagger’ом. Но вы можете попробовать это на собственной инсталляции.
При нажатии на Execute Swagger UI сформирует строку curl, с помощью которой можно аналогичный запрос сделать из командной строки.
В Swagger UI можно даже создать объект:
Для этого достаточно быть авторизованным пользователем, обладающим нужными правами.
То, что мы видим на этой странице — это Swagger UI — документация, сгенерированная на основе спецификации API.
С трендами на микросервисную архитектуру всё более важным становится иметь стандартизированный API для взаимодействия между компонентами, эндпоинты и методы которого легко определить как человеку, так и приложению, не роясь в исходном коде или PDF-документации.
Поэтому разработчики сегодня всё чаще следуют парадигме API First, когда сначала задумываются об API, а уже потом о реализации.
В этом дизайне сначала специфицируется API, а затем из него генерируются документация, клиентское приложение, серверная часть и необходимы тесты.
Swagger — это фреймворк и язык спецификации (который ныне переименован в OpenAPI 2.0), позволяющие реализовать эту задачу.
Углубляться в него я не буду.
За бо́льшими деталями сюда:
Критика REST и альтернативы
Существует и такая, да. Не всё в том мире 2000-го года так уже радужно.
Не являясь экспертом, не берусь предметно раскрывать вопрос, но дам ссылку на небесспорную статью на Хабре.
Альтернативным интерфейсом взаимодействия компонентов системы сегодня является gRPC. Ему же пророчат большое будущее на ниве новых подходов к работе с сетевым оборудованием. Но о нём мы поговорим когда-то в будущем, когда придёт его черёд.
Можно также взглянуть на многообещающий GraphQL, но нам опять же нет нужды с ним работать пока, поэтому остаётся на самостоятельное изучение.
Важно
Токен a9aae70d65c928a554f9a038b9d4703a1583594f был использован только в демонстрационных целях и больше не работает.
Прямое указание токенов в коде программы недопустимо и сделано здесь мной только в интересах упрощения примеров.