хабр что такое api
Простой API gateway на базе PHP и Lumen
Термин «микросервисы» сегодня у всех на слуху – внезапно это стало очень модно, и многие компании объявляют переход на этот архитектурный паттерн даже толком не разобравшись в нём. Впрочем, обсуждение полезности микросервисов оставим за пределами этой статьи.
Традиционно перед коллекцией микросервисов предлагается дополнительный слой – так называемый API gateway, который решает сразу несколько проблем (они будут перечислены позже). На момент написания этой статьи open source реализаций таких gateway почти нет, поэтому я решил написать свой на PHP с использованием микрофреймворка Lumen (часть Laravel).
В этой статье я покажу насколько это простая задача для современного PHP!
Что такое API gateway?
Если говорить совсем коротко, то API gateway – это умный proxy-сервер между пользователями и любым количеством сервисов (API), отсюда и название.
Необходимость в этом слое появляется сразу же при переходе на паттерн микросервисов:
Nginx выпустили неплохую бесплатную электронную книгу посвященную микросервисам и API gateway – советую почитать всем, кому интересен этот паттерн.
Существующие варианты
Почему PHP и Lumen?
С выходом версии 7 PHP стал высокопроизводительным, а с появлением фреймфорков вроде Laravel и Symfony – PHP доказал миру, что может быть красивым и функциональным. Lumen, являясь «очищенной» быстрой версией Laravel здесь идеально подходит, ведь нам не нужны будут сессии, шаблоны и прочие возможности full stack приложений.
Кроме того, у меня просто больше опыта с PHP и Lumen, а разворачивая полученное приложение через Docker – будущим пользователям вообще будет не важен язык, на котором оно написано. Это просто слой, который выполняет свою роль!
Выбранная терминология
Мною предлагается следующая архитектура и соответствующая ей терминология. В коде буду придерживаться этих терминов, чтобы не запутаться:
Само приложение решил назвать Vrata, потому что «врата» на русском это почти «gateway», а ещё миру не хватает приложений с русскими названиями )
Непосредственно за «вратами» находится количество N микросервисов – API сервисов, способных отвечать на web-запросы. У каждого сервиса может быть любое количество экземпляров, поэтому API gateway будет выбирать конкретный экземпляр через так называемый реестр сервисов.
Каждый сервис предлагает какое-то количество ресурсов (на языке REST), а у каждого ресурса может быть несколько возможных действий. Достаточно простая и логичная структура для любого опытного в REST программиста.
Требования к Vrata
Ещё не приступив к коду, можно сразу определить некоторые требования к будущему приложению:
Реализация
Аутентификация
В этом направлении почти не пришлось работать – достаточно было поправить Laravel Passport под Lumen и мы получили поддержку всех современных OAuth2 фич, включая JWT. Мой маленький пакет-порт опубликован на GitHub/Packagist и кто-то его уже устанавливает.
Маршруты и контроллер
Все низлежащие маршруты с микросервисов импортируются в Vrata из конфигурационного файла в формате JSON. В момент запуска в service provider происходит добавление этих маршрутов:
А тем временем в базе маршрутов:
Теперь каждому публичному (и разрешенному в конфигах) маршруту с микросервисов соответствует маршрут на API gateway. Кроме того, добавлены также синтетические или объединенные запросы, которые существуют только на этом шлюзе. Все запросы уходят в один и тот же контроллер:
Вот так контроллер обрабатывает любой GET-запрос:
В качестве HTTP-клиента выбран Guzzle, который прекрасно справляется с async-запросами, а также имеет готовые средства для integration-тестирования.
Составные запросы
Уже работают сложные, составные запросы – это когда одному маршруту на шлюзе соответствует любое количество маршрутов на разных микросервисах. Вот рабочий пример:
Как видим, сложные маршруты уже доступны и обладают неплохим набором фич – можно выделать критически важные из них, можно делать параллельные запросы, можно использовать ответ одного сервиса в запросе к другому и так далее. Помимо всего прочего, на выходе прекрасная производительность – всего 56 миллисекунд на получение суммарного ответа (загрузка Lumen и три фоновых запроса, все микросервисы с базами данных).
Реестр сервисов
Это пока самая слабая часть – реализован только один очень простой метод: DNS. Несмотря на всю его примитивность, он отлично работает в среде вроде Docker Cloud или AWS, где сам провайдер наблюдает за группой сервисов и динамически редактирует DNS-запись.
В настоящий момент Vrata просто берет hostname сервиса, не вникая – облако это или один физический компьютер. Самым популярным реестром на сегодня, пожалуй, является Consul, и именно его стоит добавить следующим.
Суть работы реестра очень проста – надо хранить таблицу живых и мертвых экземпляров сервиса, выдавая адреса конкретных экземпляров когда надо. AWS и Docker Cloud (и многие другие) умеют это делать за вас, предоставляя вам один «волшебный» hostname, который всегда работает.
Образ Docker
Говоря о микросервисах просто нельзя не упомянуть Docker – одну из самых «горячих» технологий последних пары лет. Микросервисы, как правило, тестируются и деплоятся именно как образы Docker – это стало стандартной практикой, поэтому мы быстро подготовили публичный образ в Docker Hub.
Одна команда, введённая в терминале любой OS X, Windows или Linux машины, и у вас работает мой шлюз Vrata:
Всю конфигурацию можно передать в переменных окружения в формате JSON.
Послесловие
Приложение (шлюз) уже используется на практике в компании, где я работаю. Весь код в репозитории на GitHub. Если кто-либо хочет поучаствовать в разработке – милости просим 🙂
Так как составные запросы как по идее, так и по реализации очень напоминают продвигаемый Facebook формат запросов GraphQL (в противовес REST), то одна из приоритетных будущих фич – поддержка GraphQL-запросов.
Разработка REST API — что такое Code First подход?
Это четвертая статья в серии статей по REST API:
Разработка хорошего REST API важна для того, чтобы иметь хорошие микросервисы. Подход Code-First фокусируется на генерации контракта из кода. Это наилучший из возможных подходов?
Вы изучите
Что такое Code-First подход?
Всякий раз, когда вы разрабатываете сервис, такой как REST API или SOAP API, вы можете выбрать один из двух подходов:
Spring Boot Code First пример REST API
Мы разрабатываем RESTful веб-сервис, используя Spring Boot Framework для генерации API. Например, в API retrieveAllUsers () мы открываем URI «/users» и
возвращаем всех пользователей (ресурс /users),
вызывая метод сервиса.
Когда мы переходим на этот URL, мы возвращаем всех пользователей:
Аналогичным образом определены и другие сервисные методы, каждый из которых имеет свой собственный URI. В этом примере мы берем код и генерируем из него документацию. В этой документации указано, как пользователь может использовать сервис. Для этого мы используем формат документации Swagger:
Swagger позволяет нам генерировать документацию из кода. Например, вот что Swagger генерирует для запроса на получение всех пользователей:
Он выводит тип получаемого нами ответного сообщения и сопровождающий его статус ответа. Вы даже можете вызвать этот сервис из Swagger получить ответ:
Вы также можете отправить запрос POST в «/users«:
Swagger сообщит нам, как структурировать сообщение запроса и указать внутри него отдельные форматы полей. Он также сообщит вам тип ответа, который вы получите, вместе с кодом ответа. То, что Swagger генерирует из кода, называется контрактом.
Преимущества Code First
Основные преимущества этого подхода:
Недостатки Code First
Недостатки этого подхода заключаются в следующем:
Нет параллельной разработки
Производитель услуг и потребители услуг не могут разрабатывать параллельно. Сначала необходимо разработать сервис, затем сгенерировать контракт, и только после этого можно написать код потребителя, который будет придерживаться контракта. Без понимания контракта потребитель не может быть разработан.
Нет цели для команд
Поскольку договор не может быть известен до того, как сервис будет разработан, не существует цели для различных заинтересованных сторон в разработке. Следовательно, есть все шансы, что направления будут отклоняться, и будут внесены ненужные изменения, что приведет к напрасной трате усилий.
Нет кроссплатформенной совместимости
На некоторых старых платформах не так просто сгенерировать контракт из кода. В результате этого для сгенерированных контрактов довольно часто возникает несовместимость между платформами.
По этому вопросу имеется авторское видео.
Резюме
В этой статье мы исследовали Code First подход построения REST API. Несмотря на то, что подход, основанный на коде, эффективен с точки зрения разработчика, он сталкивается с серьезными проблемами, когда речь идет о совместной разработке поставщика и потребителя.
Проектирование Web API в 7 шагов
Разработка веб API это нечто большее чем просто URL, HTTP статус-коды, заголовки и содержимое запроса. Процесс проектирования – то, как будет выглядеть и восприниматься ваш API – очень важен и является хорошей инвестицией в успех вашего дела. Эта статья кратко описывает методологию для проектирования API с опорой на преимущества веба и протокола HTTP, в частности. Но не стоит думать, что это применимо только для HTTP. Если по какой-то причине вам необходимо реализовать работу ваших сервисов используя WebSockets, XMPP, MQTT и так далее – применяя большую часть всех рекомендаций вы получите практически тот же API, который будет хорошо работать. К тому же полученный API позволит легче разработать и поддерживать работу поверх нескольких протоколов.
Хороший дизайн затрагивает URL, статус-коды, заголовки и содержимое запроса
Обычно руководства по проектированию Web API фокусируются на общих концепциях: как проектировать URL, как правильно использовать HTTP статус-коды, методы, что передавать в заголовках и как спроектировать дизайн содержимого, которое представлено сериализованными данными или графом объектов. Это всё очень важные детали реализации, но не настолько в смысле общего проектирования API. Проектирование API – это то, как сама суть сервиса будет описана и представлена, то что вносит значительный вклад в успех и удобность использования Web API.
Хороший процесс проектирования или методология предоставляют набор согласованных и воспроизводимых шагов для создания компонентов сервисов, которые будут доступны в виде Web API. Это значит, что такая прозрачная методология может быть использована разработчиками, дизайнерами и архитекторами для координации своих действий по реализации ПО. Использованная методология так же может уточнятся со временем по мере того, как улучшается и автоматизируется процесс без ущерба для деталей методологии. На самом деле, детали реализации могут меняться (например, платформа, ОС, фреймворки и стиль UI) независимо от процесса проектировки, когда эти две активности полностью разделены и задокументированы.
Проектирование API в 7 шагов.
Далее следует краткий обзор методологии описанной в книге «RESTful Web APIs» за авторством Ричардсона и Амундсена (Richardson and Amundsen). Статья не предполагает детального разбора каждого шага, но постарается дать общее понимание что делается на каждом шаге. Также, читатели могут использовать этот обзор как руководство для разработки процесса проектирования Web API, который учитывает специфику ваших знаний и целей бизнеса.
Заметки на полях: Да, руководство в семь шагов может выглядеть достаточно большим, но реально тут только 5 шагов по проектированию и 2 как дополнения, касающиеся реализации и публикации сервисов. Эти два дополнения построены вокруг процессов и описывают весь процесс от начала до конца.
В своём плане вы должны учесть возможную итеративную природу процесса создания сервиса. Например, вы можете проходить через Шаг 2 (Создание диаграмм состояний) и понять, что надо еще кое-чего сделать в Шаге 1 (Перечислить все компоненты). Когда вы будете писать код (Шаг 6), вы можете обнаружить, что пропустили пару моментов в Шаге 5 (Создание семантического профиля), и так далее. Ключевой момент заключается в использовании руководства для обнаружения как можно большего количества деталей и желании возвращаться на шаг-два назад, чтобы описать пропущенные моменты. Итеративность – ключ к построению наиболее полного представления вашего сервиса и видению как он может быть использован клиентскими приложениями.
Шаг 1: Перечислить все компоненты
Первым шагом предлагается перечислить все типы данных, которые клиентское приложение может захотеть получить или передать с помощью сервиса. Мы зовём это семантическим описанием. Семантическое – потому что отображает значение данных в приложении, и описание – потому что содержит описание того, что происходит в самом приложении. Заметьте, что вы должны работать с точки зрения клиентского приложения, а не сервиса. Важно разработать удобный API для использования клиентом.
Шаг 2: Нарисовать диаграмму состояний
Следующим шагом будет нарисовать диаграмму состояний для предполагаемого API. Каждый блок на диаграмме представляет возможное состояние – документ который включает одно или более семантических дескрипторов, найденных на первом шаге. Вы можете использовать стрелки для обозначения переходов от одного блока к другому, от одного состояния к следующему. Эти переходы инициируются запросами.
Пока не стоит беспокоится на счёт определения какой метод используется для каждого перехода. Просто укажите является ли переход безопасным (HTTP GET), небезопасный/не идемпотентный (HTTP POST) или небезопасный/идемпотентный (PUT)
Заметки на полях: Идемпотентные действия – такие, которые можно повторять без неожиданных сайд-эффектов. Например, HTTP PUT является идемпотентным потому что спецификация говорит, что сервер должен использовать значения состояния, полученные от клиента, для замены любых значений в целевом ресурсе. В то время как HTTP POST не идемпотентен, так как спецификация HTTP указывается что значения, переданные с помощью POST должны быть добавлены к существующим ресурсам, а не замещены.
В нашем случае, клиентское приложение для простейшего «Списка дел» может потребовать доступ к пунктам списка, возможность фильтрации, просматривать отдельные пункты и отмечать их как завершённые. Многие из этих действий используют значения состояний для передачи данных между клиентом и сервером. Например, действие «добавить элемент» позволяет клиенту передавать значения состояний title и dueDate. Ниже диаграмма, которая иллюстрирует основные действия:
Как только вы пройдёте пару раз через эти два шага у вас будет хорошее понимание всех данных и действий в которых нуждается клиент для взаимодействия с вашим сервисом.
Шаг 3: Согласование магических строк
Заметки на полях: Использование общих имён для дескрипторов может быть хорошей идеей для внешнего интерфейса, однако вас никто не заставляет использовать их для ваших внутренних нужд. Имеются ввиду, например, имена для баз данных. Сервис самостоятельно может использовать карту соответствий между внешними и внутренними именами без каких-либо проблем.
Для To-Do сервиса из примера, у меня получилось найти приемлемые существующие имена для всех дескрипторов кроме одного – «create-item». В этом случае, я обратился к созданию уникального URI на основе правил из Web-Linking RFC 5988. Во время выбора конвенционных имён для интерфейса вас всегда будут преследовать компромиссы. Редко когда удаётся найти идеальное попадание к внутренним именам и это нормально.
Шаг 4: Выбор типа гипермедиа
Следующим шагом в процессе проектирования вашего API будет выбор типа данных, который будет использоваться для передачи сообщений между сервером и клиентом. Одним из отличительных знаков сети является то, что данные передаются стандартизированными документами через общий интерфейс. Очень важно выбрать такой тип, который поддерживает одинаково дескрипторы данных («identifier», «status») и действий («search», «edit»). Таких форматов достаточно мало.
Разработка web API
Интро
Это краткий перевод основных тезисов из брошюры «Web API Design. Crafting Interfaces that Developers Love» Брайана Маллоя из компании Apigee Labs. Apigee занимается разработкой различных API-сервисов и консталтингом. Кстати, среди клиентов этой компании засветились такие гиганты, как Best Buy, Cisco, Dell и Ebay.
В тексте попадаются комментарии переводчика, они выделены курсивом.
Собираем API-интерфейсы, которые понравятся другим разработчикам
Понятные URL для вызовов API
Первый принцип хорошего REST-дизайна — делать вещи понятно и просто. Начинать стоит с основных URL адресов для ваших вызовов API.
Ваши адреса вызовов должны быть понятными даже без документации. Для этого возьмите себе за правило описывать любую сущность с помощью коротких и ясных базовых URL адресов, содержащих максимум 2 параметра. Вот отличный пример:
/dogs для работы со списком собак
/dogs/12345 для работы с отдельной собакой
Существительные — это хорошо, а глаголы — плохо
Видите эти вызовы? Это ужас.
Вместо глаголов — HTTP
POST /dogs — создать новую собаку
GET /dogs — получить список собак
PUT /dogs — редактирование всех собак сразу
DELETE /dogs — удаление всех собак
POST /dogs/12345 — вернуть ошибку (собака 12345 уже создана)
GET /dogs/12345 — показать информацию о собаке
PUT /dogs/12345 — редактировать собаку 12345
DELETE /dogs/12345 — удалить
Базовые URL выглядят просто, глаголы не используются, все интуитивно и понятно. Красота!
Множественное число
/checkins у Foursquare
/deals y GroupOn
/Product y Zappos
Конкретные имена лучше абстрактных
Абстрактные названия — это часто считается крутым у архитекторов API. И это совсем не круто для тех, кто потом с этим API будет работать.
/blogs, /videos, /news, /articles — это выглядит очевидным. А вот /items и /assets — нет.
Связи
Мы только что представили связь двух ресурсов в простом виде. Метод GET в этом случае вернет нам список собак владельца 5678, а метод POST — добавит владельцу 5678 еще одну собаку.
Связи очень удобно представлять в виде /ресурс/идентификатор/ресурс.
Сложные вещи нужно прятать за знаком «?»
А что насчет ошибок?
SimpleGeo дают сообщение об ошибке в коде HTTP и снабжают его небольшим пояснением в теле ответа.
Используйте коды ответов HTTP
Google GData
200 201 304 400 401 403 404 409 410 500
Netflix
200 201 304 400 401 403 404 412 500
Digg
200 400 401 403 404 410 500 503
Какие коды ошибок HTTP стоит использовать?
И, конечно же, при ошибке всегда нужно прикладывать сообщение для разработчиков. А приложить к сообщению ссылку на документацию по проблеме — это еще лучше.
Никогда не выпускайте API без указания версии
Twilio требует при каждом запросе к API передавать время, когда приложение разработчика было скомпилировано. На основе этой даты Twilio определяет, какую версию API нужно предоставить приложению. Это умный и интересный подход, но слишком сложный. А еще можно легко запутаться с датами.
Salesforce.com вставляет v20.0 в середину адреса API запроса. И это очень хороший подход. Но не стоит использовать точку в нумерации версии — это провоцирует излишне частые изменения в интерфейсе API. Можно сколь угодно часто менять логику работы внутри API, но вот сами интерфейсы должны меняться максимально редко. Так что лучше обойтись без точки и не искушать себя.
Facebook тоже использует нумерацию версий в запросе, но прячет её в параметры запроса. И этот подход плох тем, что после очередного внедрения новой версии API все приложения, не передающие версию в запросе, начинают глючить.
Как реализовать версии в API?
Используйте префикс v, целые числа и располагайте номер версии в левой части адреса. Например, /v1/dogs.
Держите в рабочем виде как минимум одну предыдущую версию
Еще можно указывать версию в заголовках ответа сервера. Это может давать некоторые дополнительные возможности при работе с API. Но если вы используете множество разных версий и требуете обязательно указывать их в заголовках — это симптом большой проблемы.
Частичный ответ
Перечислять необходимые поля через запятую в адресе запроса — это очень простой и удобный подход. Берите его на вооружение.
Сделайте простую паджинацию
Facebook: смещение 50 и лимит 25
Twitter: страница 3 и 25 записей на страницу
Linkedin: с 50-й записи прочитать 25
Еще стоит приложить к каждому ответу мета-информацию: текущая страница, сколько всего записей доступно.
Предусмотрите значения по умолчанию: если пользователь не передал в запросе параметры паджинации, считайте лимит равным 10 и смещение — равным 0 (вывести первые 10 записей).
А что насчет действий?
Не все API-ресуры являются записями, которые можно читать, редактировать и удалять. Бывают и API-действия. Переводы, вычисления, конвертации — все это действия.
Лучше всего для таких запросов использовать глаголы, а не существительные.
Убедитесь, что даже просто глядя на список вызовов в документации можно отличить сущности от действий.
Поддержка нескольких форматов
Кстати, Digg позволяет установить формат ответа и через HTTP-заголовок Accept.
Мы рекомендуем подход Foursquare.
Еще можно предусмотреть ответы API не только в разных форматах, но и ответы для разных типов клиентов. Например, можно сделать API, способное работать одновременно с iOS-приложением и фронт-эндом веб-приложения. Это может выглядеть так: /dogs.ios и /dogs.web.
Формат по умолчанию
JSON — пожалуй, лучший формат по умолчанию. Он менее многословен, чем XML. Его поддерживают все популярные языки. Его можно сразу же использовать на фронт-энде веб-приложения.
Названия атрибутов
Twitter created_at
Bing DateTime
Foursquare createdAt
Существует много конвенций именования переменных. Нам, как спецам по Ruby on Rails, конвенция Twitter близка по духу. Но лучшим подходом мы считаем подход Foursquare: — camelCase (переменные с маленькой буквы, классы — с большой). Такой способ именования наиболее симпатичен для подачи данных в JSON: данные выглядят похоже на JavaScript. Что, в общем, логично для JSON.
Хоть автор и советует почаще использовать camelCase, лучше все же подумать о клиенте и потом уже принимать решение. Например, с вашим API может общаться программа, написанная на C, а ей лучше использовать несколько_другую_конвенцию.
Поиск
Соберите все API вызовы на одном домене
api.facebook.com этот адрес появился первым
graph.facebook.com этот адрес ввели после внедрения глобального графа
stream.twitter.com
api.twitter.com
search.twitter.com
Легко догадаться, как Facebook и Twitter завели себе по несколько адресов: проще направлять запросы в разные кластеры через DNS, чем через логику. Но мы делаем приятный API для разработчиков, поэтому опять выберем подход Foursquare.
На всякий случай напомню, что разработчикам небольшого бэкенда для веб-приложения не надо выделять отдельный домен, чтобы не создавать проблемы с кроссдоменными ajax-запросами на фронт-энде.
Делайте редиректы
Коды HTTP ответов и исключения на клиенте
В результате ошибки будут приходить с кодом 200.
Предусмотрите в своем API параметр suppress_response_codes и сделайте его равным true по умолчанию.
А что если клиент поддерживает ограниченный набор HTTP методов?
чтение /dogs
создание /dogs?method=post
редактирование /dogs/1234?method=put
удаление /dogs/1234?method=delete
Будьте аккуратны с таким подходом! Если вы будете неаккуратно обращаться с такими ссылками и не обеспечите им должной безопасности, боты (вроде поискового робота Google) могут вызывать такие ссылки. И вы получите бесконечно создающиеся и удаляющиеся записи при каждом заходе бота.
Авторизация
PayPal Permissions Service API
Facebook OAuth 2.0
Twitter 1.0a
Обратите внимание на то, что PayPal реализовали свою систему авторизации еще до того, как был изобретен OAuth.
Если вам требуется авторизация пользователей через сторонние приложения — только OAuth. И ни в коем случае не делайте что-то вроде OAuth, но «немного другое».
«Болтливые» API
«Болтливые» — это значит, что для выполнения популярных операций приходится выполнять 3-4 вызова API подряд. Это плохо.
Попробуйте посмотреть на ваши вызовы глазами пользователя. Вы увидите, что примерно 80% вызовов принимают и отдают данные одинаковой структуры. Это значит, что вполне можно сделать псевдонимы для последовательностей вызовов. После этого пользователь сможет единожды направить данные на вход, и вся цепочка вызовов выполнится сама.