endpoint url что это

Автоматизация Для Самых Маленьких. Заметки. 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 был использован только в демонстрационных целях и больше не работает.

Прямое указание токенов в коде программы недопустимо и сделано здесь мной только в интересах упрощения примеров.

Источник

Базовые знания REST API

Каждое понятие ниже играет важную роль в понимании WordPress REST API. Давайте ознакомимся с понятиями и фразами, которые используются в этом руководстве, чтобы иметь представление о чем речь. Подробнее каждое понятие прямо или косвенно рассмотрено в других разделах этого руководства.

Это простой и удобный формат данных, который выглядит как объект в JavaScript, отсюда и название (JavaScript Object Notation). Пример JSON формата:

REST получает и отдает JSON. Это позволяет разработчикам создавать, читать и обновлять контент WordPress с клиентского JavaScript или из внешних приложений, написанных на любом языке программирования.

HTTP Клиент (или просто Клиент)

Инструмент, который используется для взаимодействия с REST API. Этот инструмент позволяет создавать HTTP запросы и умеет обрабатывать полученные ответы.

Таким инструментом может быть:

Маршруты и Эндпоинты

Разберем URL

Запрос к корневому маршруту

Маршрут без ЧПУ

Пространство имён

Пространство имен нужно, чтобы сделать название маршрута уникальным и таким образом избежать конфликтов при создании множества маршрутов разными плагинами/темами.

Еще одно преимущество использования пространства имён — это то, что Клиенты смогут обнаружить ваше произвольное API. Список пространств отображается по главному запросу на корневой URL REST API:

При регистрации произвольных маршрутов настоятельно рекомендуется указывать пространство имени!

Что если не указать пространство имени?

Сокращение от Create, Read, Update, Delete. Это короткое название всех видов операций маршрута, которые он позволяет делать: читать, создавать, обновлять и удалять что-либо (ресурс).

Ресурс

Ресурсы — это сущности в WordPress — это Посты, Страницы, Комментарии, Юзеры, Элементы таксономий (термины) и т.д.

WP-API позволяет HTTP-клиентам выполнять CRUD операции с ресурсами (create, read, update, delete).

Пример того, как REST API взаимодействует с ресурсами:

Путь к ресурсу

Запрос

Один из основных классов в структуре WordPress REST API это WP_REST_Request. Этот класс используется для получения информации из запроса.

Запрос может быть отправлен удаленно через HTTP или внутренне из PHP. Объекты WP_REST_Request создаются автоматически при каждом запросе HTTP к маршруту. Данные, указанные в запросе определяют, какой ответ будет получен.

Ответ

Ответ — это данные которые вернуться из API в ответ на запрос. Ответы от конечных точек управляются классом WP_REST_Response. Класс предоставляет разные способы взаимодействия с данными ответа.

Ответы могут возвращать разные данные, в том числе JSON объект ошибки:

В заголовках ответа также указывается его статус код (200, 401). В REST API статус код часто важен, на его основе можно понять что не так с запросом. Подробнее про статус коды смотрите в отдельном разделе.

HTTP Методы

HTTP метод указывается при запросе Клиентом и определяет тип действия, которое Клиент хочет выполнить над ресурсом.

Методы которые используются в WP API:

Не все клиенты поддерживают все эти методы или может быть на сервере установлен фаервол, который запрещает некоторые методы.

Поэтому в WP API есть возможность указать такой метод по-другому:

Схема

Схема в REST API — это полное описание маршрута, оно рассказывает нам о маршруте все:

Под словом «схема» можно понимать разные Схемы. В общем смысле — это Схема маршрута — это общая схема всего маршрута, в которую входят две схемы:

В WP API схема представлена в виде JSON объекта и получить его можно сделав OPTIONS запрос на маршрут. Схема предоставляет машиночитаемые данные, поэтому любой Клиент который умеет читать JSON может понять с какими данными ему предстоит работать.

Рассмотрим пример

Возьмем маршрут /wp/v2/categories и посмотрим его схему:

Схемы эндпоинтов:

В ключе endpoints мы видим «Схемы эндпоинтов», т.е. какие у маршрута есть конечные точки. Их тут две: GET (получит рубрики) и POST (создаст рубрику). И тут же описаны все возможные параметры для этих конечных точек.

Вот код схемы одного эндпоинта из кода выше (этот эндпоинт создает рубрику):

Схема ресурса:

В ключе schema мы видим «Схему ресурса», т.е. все аргументы JSON объекта, которые вернет API в случае удачного CRUD запроса.

Так выглядит схема ресурса (рубрики) из кода выше:

Вот более читаемый вариант схемы ресурса (рубрики) из кода выше:

Контекст в схеме

Контекст — показывает какие поля объекта вернуться в ответе при создании запроса в указанном контексте. Например, при обновлении или создании рубрики вернуться поля соответствующие контексту edit.

Обнаружение

Это процесс выяснения любых деталей о работе с REST API. Например:

Контроллер

Классы контроллеров объединяют отдельные части REST API в единый механизм. В них должны создаваться маршруты, они должны обрабатывать запросы, генерировать ответы API и описывать схему ресурса.

Подробнее читайте в разделе Классы контроллеров!

Источник

Шаг 2 «Конечные точки и методы (Описание API)»

Конечные точки указывают, как получить доступ к ресурсу, а метод указывает разрешенные взаимодействия (такие как GET, POST или DELETE) с ресурсом.

Один и тот же ресурс обычно имеет множество связанных конечных точек, каждая из которых имеет разные пути и методы, но возвращает различную информацию об одном и том же ресурсе. Конечные точки обычно имеют краткие описания, похожие на общее описание ресурса, только еще короче. Кроме того, конечная точка показывает только конечный путь URL ресурса, а не базовый, общий для всех конечных точек, путь.

Примеры конечных точек

Вот пример конечной точки ресурса User API Instagram

Конечная точка обычно выделяется стилизованным образом для придания ей более визуального внимания. Большая часть документации строится вокруг конечной точки, поэтому, может, имеет смысл визуально выделить конечную точку в нашей документации.

Конечная точка, возможно, является наиболее важным аспектом документации API, потому что она является тем, что разработчики будут реализовывать для выполнения своих запросов.

Представление параметра path при помощи фигурных скобок

Параметры path в конечных точках, представляют в фигурных скобках. Например, вот пример из API Mailchimp:

По возможности, параметр path выделяют другим цветом:

Фигурные скобки для параметров path являются условием, понятным пользователям. В приведенном выше примере почти ни одна конечная точка не использует фигурные скобки в синтаксисе фактического пути, поэтому является очевидным плэйсхолдером.

Вот пример из API Facebook, где параметр path выделен цветом для его легкой идентификации:

Для выделения параметров, при их описании в документации Facebook, используется зеленый цвет, который помогает пользователям понять их значение.

Параметры path не всегда выделяются уникальным цветом (например, некоторым может предшествовать двоеточие), но, как бы то ни было, нужно убедиться, что параметр path легко идентифицируется.

Перечисляем методы конечной точки

Для конечной точки обычно перечисляют методы (GET, POST и т. Д.). Метод определяет работу с ресурсом. Вкратце, каждый метод выглядит следующим образом:

См. Request methods в статье Wikipedia по HTTP для получения дополнительной информации. (Существуют дополнительные методы, но они редко используются.)

Поскольку о самом методе особо говорить нечего, имеет смысл сгруппировать метод с конечной точкой. Вот пример из Box API:

А вот пример API LinkedIn:

Конечная точка показывает только конечный путь

Когда мы описываем конечную точку, мы указываем только конечный путь (отсюда и термин «конечная точка»). Полный путь, который содержит как базовый путь, так и конечную точку, часто называют URL-адресом ресурса.

Как сгруппировать несколько конечных точек одного ресурса

Еще стоит обращать внимание при документировании конечных точек и методов, как группировать и перечислять конечные точки, особенно если у нас много конечных точек для одного и того же ресурса. В Примерах описания ресурсов мы рассмотрели различные API. Многие сайты документации используют различные схемы группировки или перечисления каждой конечной точки ресурса, поэтому не будем возвращаться к тем же примерам. Группируйте конечные точки таким образом, осмысленно, например, по методу или по типу возвращаемой информации.

Если конечные точки в основном совпадают, объединение их на одной странице может иметь смысл. Но если они в значительной степени уникальны (с разными ответами, параметрами и сообщениями об ошибках), разделение их на разные страницы, вероятно, лучше (и проще в управлении). Опять же, создав более сложный дизайн сайта, мы можем сделать большую информацию доступной для навигации на той же странице.

Как ссылаться к конечным точкам в инструкциях

Как ссылаться к конечным точкам в разделе API в руководствах и другом безадресном контенте? Ссылка на конечную точку /aqi или на конечную точку /weatherdata не имеет большого значения. Но для более сложных API-интерфейсов использование конечной точки для описания ресурса может оказаться непростым делом.

В одной компании URL-адреса конечных точек ресурса Rewards выглядели так:

А Rewards в контексте Missions выглядели вот так:

Сказать, что можно использовать ресурс Rewards, не всегда было достаточно конкретно, потому что было несколько Rewards и конечных точек Missions.

Чем длиннее конечная точка, тем более громоздкой становится ссылка. Эти виды описаний будут чаще встречаться в концептуальных разделах вашей документации. Как правило, нет четкого правила, как ссылаться на громоздкие конечные точки. Смысловой подход нашего API определим самостоятельно.

Конечная точка API surfReport

Давайте создадим описание «Конечные точки и методы» для нашего вымышленного API Surfrefport. Вот пример:

Следующие шаги

Теперь, когда мы описали ресурс и перечислили конечные точки и методы, пришло время заняться одной из самых важных частей API: раздел “Параметры”.

Источник