на чем писать rest api
Платформа для быстрого создания RESTful API
За последние несколько лет мне пришлось создать много API на PHP. Большая часть из них была RESTful. Первый раз это было интересно — часы обсуждения формата ответа, содержимого ошибок, вариантов авторизации и прочей романтики. Во второй раз не покидало чувство дежавю. На третий раз уже было понятно — надо что-то менять…
Ну и на четвёртый раз, когда передо мной поставили задачу создания API, параллельно разработке основного проекта, я приступил к созданию универсальной платформы для создания API в котором уже будут решены все «главные» вопросы:
api-platform
Сайт: api-platform.com
Очень мощное решение. Сделано на основе php-фреймворка Symfony. Есть всё что нужно и даже больше. Наверно, для тех кто любит программирование через конфигурации и Symfony, это то что нужно. Увы я не отношусь к этой категории.
apigility
Сайт: apigility.org
Не менее мощное решение. На этот раз на основе фреймворка Zend. Это даже какая-то CMS для создания API, причём и RESTful и RPC. Наверно, для тех кто любит программирование с помощью мышки, это то что нужно. Увы я и к этой категории не отношусь.
Есть и другие решения, вот неплохая подборочка.
Но в итоге ничего милого моему сердцу выбрать не удалось. Зато удалось сформировать несколько принципов и требований к будущему проекту:
Моё решение
Америки я не открыл. Просто взял хорошие компоненты, собрал их вместе, написал весь необходимый boilerplate-код для работы и собрал composer проект.
Краеугольный камень — это стандарт представления jsonapi. С помощью него решены почти все «холиварные» вопросы. Мне осталось только принять решение по формату запросов с фильтрацией, сортировкой и постраничной навигацией. За вывод отвечает пакет json-api от neomerx (Кстати, не так давно он тоже собрал свой api starter pack).
В качестве основы я выбрал Slim3. Грамотно спроектированный, быстрый, легко расширяемый и простой.
Для работы с БД ORM Eloquent. Удобная, сравнительно быстрая и простая.
Работу с правами и контролем доступа построил на основе Zend ACL. На удивление простой пакет для работы с правами.
Авторизация на основе JWT токенов
Документацию генерирую по комментариям написанным в коде с помощью ApiDocJS. Почему не Swagger? Пробовал и его, но мне apidoc понравился больше.
Код размещён на github, проект доступен на packagist.
Сразу после установки у вас будет полностью готовое API со всем необходимым. Буду рад, если кто-то применит пакет в работе. Я уже успел сделать 1 проект на нём (+ тот проект, который делал параллельно с bootstrapi) — полёт нормальный.
Лучшие практики разработки REST API: 20 советов
Авторизуйтесь
Лучшие практики разработки REST API: 20 советов
Наверняка вам попадался ужасный API, работая с которым приходилось угадывать, что он ждёт на входе, и что вы получите на выходе. В этой статье мы поговорим о лучших практиках по разработке REST API.
Немного терминов
Дизайн любого API должен следовать правилам Дизайна Ориентированного на Ресурсы. Здесь есть три ключевые идеи:
1. Используйте kebab-case для URL
Вот пример для списка заказов.
2. Используйте camelCase для параметров
Вот пример получения списка продуктов в магазине.
3. Используйте множественное число для коллекций
Если вы хотите получить всех пользователей.
4. URL должен начинаться с коллекции и заканчиваться идентификатором
Это позволяет обеспечить единство и непротиворечивость дизайна.
Такой вариант плох тем, что указывает на свойство вместо ресурса.
5. Не используйте глаголы в URL ресурсов
Вместо этого пользуйтесь HTTP методами для описания операций.
6. Пользуйтесь глаголами в URL операций
Например, если вы хотите переслать уведомление пользователю.
Помните, что resend не является CRUD операцией. Наоборот, это функция, которая выполняет определённое действие на сервере.
7. Используйте camelCase для JSON свойств
8. Состояние
RESTful HTTP сервисы обязаны реализовывать методы /health, /version и /metrics.
/health
Ответ на этот запрос — код статуса «200 OK».
/version
Этот запрос возвращает номер версии.
/metrics
Этот запрос возвращает различные метрики вроде времени ответа.
Также рекомендуется реализовать запросы /debug и /status.
9. Используйте инструменты для разработки REST API
Для этих целей достаточно хороших решений, например API Blueprint и Swagger.
С такими инструментами легко обеспечить пользователей адекватной документацией к вашему REST API.
10. Используйте простой порядковый номер для версий
И всегда указывайте его на самом верхнем уровне.
11. Указывайте количество ресурсов в ответе на запрос
Это свойство можно назвать total.
12. Используйте параметры limit и offset
Потому что на фронтенде часто требуется пагинация.
13. Используйте параметр fields
Количество возвращаемых данных имеет значение. С помощью этого параметра пользователи смогут получать только нужные им поля с данными.
Вы получите в ответе только поля name, address и contact.
В некоторых случаях это поможет уменьшить вес ответа.
14. Не передавайте аутентификационные токены в URL
Это очень плохая практика, потому что часто URL логгируются, и токен также сохранится.
Вместо этого пользуйтесь заголовками.
Помните — время жизни токена нужно ограничивать.
15. Проверяйте Content-Type
16. Используйте HTTP методы для CRUD операций
В этом и есть их смысл.
GET: получение данных о ресурсах.
POST: создание новых ресурсов и подресурсов.
PUT: обновление существующих ресурсов.
PATCH: обновляет только определённые поля существующих ресурсов.
DELETE: удаляет ресурсы.
17. URL должен отражать структуру вложенных ресурсов
18. CORS
Используйте заголовки для совместного использования ресурсов (CORS) в тех случаях, когда API доступен публично.
Рассмотрите возможность поддержки разрешенного CORS источника «*» и принудительной авторизации с помощью валидных токенов OAuth.
Избегайте сочетания использования идентификационных данных пользователя и валидации источника.
19. Безопасность
Обязательно используйте HTTPS (TLS-encrypted) для всех конечных точек, ресурсов и сервисов.
Также сделайте обязательным HTTPS для всех коллбеков URL, конечных точек пуш-уведомлений и вебхуков.
20. Ошибки
Ошибки сервисов возникают, когда клиент делает некорректный запрос или передаёт неверные данные сервису, и сервис отклоняет запрос.
Например неправильные аутентификационные данные, параметры, id версий и тд.
Золотые правила
Эти правила помогут вам принимать верные решения во время разработки REST API:
3 лучших инструмента для описания RESTful API
Взаимодействие различных сервисов с использованием АPI, из новаторства превращается в обыденность. Количество бесплатных и платных API уже исчисляется тысячами, и с каждым днем их число активно растет. А почему бы и нет? Продажа удаленных запросов к своему новаторскому сервису может принести больше прибыли, чем распространение услуг через свою площадку. И пусть, в таком случае, уже ваши клиенты ломают голову и тратят деньги на привлечение аудитории. Используя свой опыт работы, я предлагаю краткий обзор лучших решений по реализации API на сегодняшний день.
В этом сегменте стартапы только начинают свое стремительное движение к популярности. Регулярно появляются новые программные решения. Существующие продукты, работая в режиме бета тестирования, еще заманивают новых пользователей с помощью бесплатных услуг.
Тем не менее, уже появились явные лидеры гонки, о которых далее пойдет речь более подробно.
www.swagger.io
Swagger уже разрабатывают достаточно давно. Это программное решение для генерации документации является де-факто лидером. Но у меня сложилось другое мнение.
В качестве разметки используется JSON. Проект имеет свой редактор (http://editor.swagger.io/). Сейчас доступен редактор версии 2.0.
Пример отображения можно увидеть по ссылке: petstore.swagger.io
К преимуществам просмотрщика можно отнести возможность воспроизведения документации с удаленных ссылок.
При отображении документации, существует форма для отправки тестового запроса со своими параметрами.
www.apiary.io
Apiary использует в качестве разметки API blueprint, разработанного на базе синтаксиса Markdown. Файл с документацией поддерживается редакторами для Markdown.
Проект имеет хороший онлайн редактор. Заметны баги с версткой сайта, в некоторых местах она недостаточно продумана. Тем не менее, смотрится значительно приятнее Swagger (но это — моя субъективная оценка).
Поддерживает генерацию примеров запроса для языков: Java, Javascript, Node.js, Perl, Python. PHP, Ruby, Go, C#, Visual Basic, Groovy, Objective-C, Swift.
Бонус: вы пишете свой проект и размещаете его на github? Тогда ваше RESTful API и SDK под него уже доступны на www.sdks.io. Этот сервис регулярно отслеживает появление новых файлов с RESTful API и автоматически генерирует SDK библиотеки под них.
На сегодняшний день существует не менее 20 различных программных решений с различной функциональностью для RESTful API. Суть этой статьи была дать краткий обзор лидеров этого сегмента. Если вам интересно изучить эту тему глубже, можете ознакомится с другими моими статьями по этой тематике:
Наилучшие практики создания REST API
Предлагаемая вашему вниманию статья, несмотря на невинное название, спровоцировала на сайте Stackoverflow столь многословную дискуссию, что мы не смогли пройти мимо нее. Попытка объять необъятное — внятно рассказать о грамотном проектировании REST API — по-видимому, удалась автору во многом, но не вполне. В любом случае, надеемся потягаться с оригиналом в градусе обсуждения, а также на то, что пополним армию поклонников Express.
Приятного чтения!
REST API – одна из наиболее распространенных разновидностей веб-сервисов, доступных сегодня. С их помощью различные клиенты, в том числе, браузерные приложения, могут обмениваться информацией с сервером через REST API.
Следовательно, очень важно правильно проектировать REST API, чтобы по ходу работы не возникало проблем. Требуется учитывать вопросы безопасности, производительности, а также удобство использования API с точки зрения потребителя.
В противном случае мы спровоцируем проблемы для клиентов, пользующихся нашими API – а это неприятно и раздражает. Если не следовать общепринятым соглашениям, то мы только запутаем тех, кто будет поддерживать наш API, а также клиентов, поскольку архитектура будет отличаться от той, которую каждый ожидает увидеть.
В этой статье будет рассмотрено, как проектировать REST API таким образом, чтобы они были просты и понятны для каждого, кто их потребляет. Обеспечим их долговечность, безопасность и скорость, так как данные, передаваемые клиентам через такой API, могут быть конфиденциальными.
Поскольку существует множество причин и вариантов отказа сетевого приложения, мы должны убедиться, что ошибки в любом REST API будут обрабатываться изящно и сопровождаться стандартными HTTP-кодами, которые помогут потребителю разобраться с проблемой.
Принимаем JSON и выдаем JSON в ответ
REST API должны принимать JSON для полезной нагрузки запроса, а также отправлять отклики в формате JSON. JSON – это стандарт передачи данных. К его использованию приспособлена практически любая сетевая технология: в JavaScript есть встроенные методы для кодирования и декодирования JSON либо через Fetch API, либо через другой HTTP-клиент. В серверных технологиях используются библиотеки, позволяющие декодировать JSON практически без вмешательства с вашей стороны.
Существуют и другие способы передачи данных. Язык XML как таковой не очень широко поддерживается во фреймворках; обычно требуется преобразование данных в более удобный формат, а это обычно JSON. На стороне клиента, особенно в браузере, не так легко обращаться с этими данными. Приходится выполнять массу дополнительной работы всего лишь для того, чтобы обеспечить нормальную передачу данных.
Формы удобны для передачи данных, особенно если мы собираемся пересылать файлы. Но для передачи информации в текстовом и числовом виде можно обойтись без форм, поскольку в большинстве фреймворков допускается передача JSON без дополнительной обработки – достаточно взять данные на стороне клиента. Это наиболее прямолинейный способ обращения с ними.
Чтобы гарантировать, что клиент интерпретирует JSON, полученный с нашего REST API, именно как JSON, следует установить для Content-Type в заголовке отклика значение application/json после того, как будет сделан запрос. Многие серверные фреймворки приложений устанавливают заголовок отклика автоматически. Некоторые HTTP-клиенты смотрят Content-Type в заголовке отклика и разбирают данные в соответствии с указанным там форматом.
Единственное исключение возникает, когда мы пытаемся отправлять и получать файлы, пересылаемые между клиентом и сервером. Тогда требуется обрабатывать файлы, полученные в качестве отклика, и посылать данные форм с клиента на сервер. Но это тема уже для другой статьи.
Также следует убедиться, что в отклике от наших конечных точек нам приходит именно JSON. Во многих серверных фреймворках данная возможность является встроенной.
Рассмотрим в качестве примера API, принимающий полезную нагрузку в формате JSON. В данном примере используется бэкендовый фреймворк Express для Node.js. Можно использовать в качестве промежуточного ПО программу body-parser для разбора тела запроса JSON, а затем вызвать метод res.json с объектом, который мы хотим вернуть в качестве отклика JSON. Это делается так:
Установим для заголовка Content-Type в отклике значение application/json; charset=utf-8 без каких-либо изменений. Метод, показанный выше, применим и в большинстве других бэкендовых фрейморков.
В названиях путей к конечным точкам используем имена, а не глаголы
В названиях путей к конечным точкам следует использовать не глаголы, а имена. Такое имя представляет объект с конечной точки, который мы оттуда извлекаем, либо которым мы манипулируем.
Дело в том, что в названии нашего метода HTTP-запроса уже содержится глагол. Ставить глаголы в названиях путей к конечной точке API нецелесообразно; более того, имя получается излишне длинным и не несет никакой ценной информации. Глаголы, выбираемые разработчиком, могут ставиться просто в зависимости от его прихоти. Например, кому-то больше нравится вариант ‘get’, а кому-то ‘retrieve’, поэтому лучше ограничиться привычным глаголом HTTP GET, сообщающим, что именно делает конечная точка.
Действие должно быть указано в названии HTTP-метода того запроса, который мы выполняем. В названиях наиболее распространенных методов содержатся глаголы GET, POST, PUT и DELETE.
GET извлекает ресурсы. POST отправляет новые данные на сервер. PUT обновляет имеющиеся данные. DELETE удаляет данные. Каждый из этих глаголов соответствует одной из операций из группы CRUD.
/articles – это ресурс REST API. Например, можно воспользоваться Express, чтобы выполнять со статьями следующие операции:
В вышеприведенном коде мы определили конечные точки для манипуляций над статьями. Как видите, в именах путей нет глаголов. Только имена. Глаголы употребляются только в названиях HTTP-методов.
Конечные точки POST, PUT и DELETE принимают тело запроса в формате JSON и возвращают отклик также в формате JSON, включая в него конечную точку GET.
Коллекции называем существительными во множественном числе
Коллекции следует именовать существительными во множественном числе. Не так часто нам требуется взять из коллекции всего один элемент, поэтому мы должны соблюдать единообразие и использовать в названиях коллекций существительные во множественном числе.
Множественное число используется, в частности, и для единообразия с принципами именования в базах данных. Как правило, в таблице содержится не одна, а много записей, и именуется таблица соответствующим образом.
При работе с конечной точкой /articles мы пользуемся множественным числом при именовании всех конечных точек.
Вложение ресурсов при работе с иерархическими объектами
Путь конечных точек, имеющих дело со вложенными ресурсами, должен составляться так: добавляем вложенный ресурс как имя пути, следующее вслед за именем родительского ресурса.
Необходимо убедиться, что в коде вложение ресурсов полностью совпадает с вложением информации в наших таблицах баз данных. Иначе возможна путаница.
Например, это можно сделать при помощи следующего кода в Express:
Это логично, поскольку comments являются дочерними объектами articles и предполагается, что у каждой статьи – свой набор комментариев. В противном случае данная структура может запутать пользователя, поскольку обычно применяется для доступа к дочерним объектам. Тот же принцип действует при работе с конечными точками POST, PUT и DELETE. Все они используют одно и то же вложение структур при составлении имен путей.
Аккуратная обработка ошибок и возврат стандартных кодов ошибок
Чтобы избавиться от путаницы, когда на API происходит ошибка, нужно обрабатывать ошибки аккуратно и возвращать коды отклика HTTP, указывающие, какая именно ошибка произошла. Таким образом те, кто поддерживает API, получают достаточную информацию для понимания возникшей проблемы. Недопустимо, чтобы ошибки обваливали систему, поэтому и без обработки их оставлять нельзя, и заниматься такой обработкой должен потребитель API.
Коды наиболее распространенных ошибок HTTP:
В вышеприведенном коде мы держим в массиве users список имеющихся пользователей, у которых известна электронная почта.
Коды ошибок всегда нужно сопровождать сообщениями, достаточно информативными для устранения ошибки, но не настолько подробными, чтобы этой информацией могли воспользоваться и злоумышленники, намеренные украсть нашу информацию или обвалить систему.
Всякий раз, когда нашему API не удается правильно завершить работу, мы должны аккуратно обработать отказ, отправив информацию об ошибке, чтобы пользователю было проще исправить ситуацию.
Разрешать сортировку, фильтрацию и разбивку данных на страницы
Базы, расположенные за REST API, могут сильно разрастаться. Иногда данных бывает настолько много, что все их невозможно вернуть за один раз, так как это замедлит систему или вообще обрушит ее. Следовательно, нам нужен способ фильтрации элементов.
Также необходимы способы разбивки данных на страницы (пагинации), чтобы за один раз мы возвращали всего несколько результатов. Мы не хотим занимать ресурсы слишком надолго, пытаясь вытянуть все запрошенные данные разом.
Как фильтрация, так и пагинация данных позволяют повысить производительность, сократив использование серверных ресурсов. Чем больше данных накапливается в базе, тем более важными становятся две эти возможности.
Вот небольшой пример, в котором API может принимать строку запроса с различными параметрами. Давайте отфильтруем элементы по их полям:
Наконец, мы применяем filter с каждым значением параметра запроса, чтобы найти те элементы, которые хотим вернуть.
Справившись с этим, возвращаем results в качестве отклика. Следовательно, при выполнении запроса GET к следующему пути со строкой запроса:
Также в строке запроса можно указать поля, по которым будет производиться сортировка. В таком случае мы можем отсортировать их по этим отдельным полям. Например, нам может понадобиться извлечь строку запроса из URL вида:
Где + означает «вверх», а – «вниз». Таким образом, мы сортируем по имени автора в алфавитном порядке и по datepublished от новейшего к наиболее давнему.
Придерживаться проверенных практик обеспечения безопасности
Коммуникация между клиентом и сервером должна быть в основном приватной, так как зачастую мы отправляем и получаем конфиденциальную информацию. Следовательно, использование SSL/TLS для обеспечения безопасности – обязательное условие.
Сертификат SSL не так сложно загрузить на сервер, а сам этот сертификат либо бесплатен, либо стоит очень дешево. Нет никаких причин отказываться от того, чтобы обеспечивать коммуникацию наших REST API по защищенным каналам, а не по открытым.
Человеку нельзя открывать доступ к большему объему информации, чем он запросил. Например, рядовой пользователь не должен получать доступа к информации другого пользователя. Также он не должен иметь возможности посмотреть данные администраторов.
Для продвижения принципа наименьших привилегий необходимо либо реализовать проверку ролей для отдельно взятой роли, либо обеспечить более точную детализацию ролей для каждого пользователя.
Если мы решаем сгруппировать пользователей по нескольким ролям, то для ролей нужно предусмотреть такие права доступа, которые обеспечивают выполнение всего, что требуется пользователю, и не больше. Если мы с большей детализацией прописываем права доступа к каждой возможности, предоставляемой пользователю, то нужно гарантировать, что администратор сможет наделять этими возможностями любого пользователя, либо отнимать эти возможности. Кроме того, необходимо добавить некоторые предустановленные роли, которые можно будет применять к группе пользователей, чтобы не приходилось выставлять нужные права для каждого пользователя вручную.
Кэшировать данные для улучшения производительности
Можно добавить возможность кэширования, чтобы возвращать данные из локального кэша памяти, а не извлекать некоторые данные из базы всякий раз, когда их запрашивают пользователи. Достоинство кэширования заключается в том, что пользователи могут получать данные быстрее. Однако, эти данные могут оказаться устаревшими. Это также бывает чревато проблемами при отладке в продакшен-окружениях, когда что-то пошло не так, а мы продолжаем смотреть на старые данные.
Существуют разнообразные варианты решений для кэширования, например, Redis, кэширование в оперативной памяти и многие другие. По мере надобности можно менять способ кэширования данных.
и этого достаточно, чтобы применить кэширование в масштабах всего приложения. Кэшируем, например, все результаты за пять минут. Впоследствии это значение можно откорректировать в зависимости от того, что нам нужно.
Версионирование API
У нас должны быть различные версии API на тот случай, если мы вносим в них такие изменения, которые могут нарушить работу клиента. Версионирование может производиться по семантическому принципу (например, 2.0.6 означает, что основная версия – 2, и это шестой патч). Такой принцип сегодня принят в большинстве приложений.
Таким образом можно постепенно выводить из употребления старые конечные точки, а не вынуждать всех одновременно переходить на новый API. Можно сохранить версию v1 для тех, кто не хочет ничего менять, а версию v2 со всеми ее новоиспеченными возможностями предусмотреть для тех, кто готов обновиться. Это особенно важно в контексте публичных API. Их нужно версионировать, чтобы не сломать сторонние приложения, использующие наши API.
Например, вот как это можно сделать в Express:
Мы просто добавляем номер версии к началу пути, ведущего к конечной точке.
Заключение
Важнейший вывод, связанный с проектированием высококачественных REST API: в них необходимо сохранять единообразие, следуя стандартам и соглашениям, принятым в вебе. JSON, SSL/TLS и коды состояния HTTP – обязательная программа в современном вебе.
Не менее важно учитывать производительность. Можно увеличить ее, не возвращая слишком много данных сразу. Кроме того, можно задействовать кэширование, чтобы не запрашивать одни и те же данные снова и снова.
Пути к конечным точкам должны именоваться единообразно. В их названиях нужно использовать существительные, поскольку глаголы присутствуют в названиях методов HTTP. Пути вложенных ресурсов должны следовать после пути родительского ресурса. Они должны сообщать, что мы получаем или чем манипулируем, так, чтобы нам не приходилось дополнительно обращаться к документации, чтобы понять, что происходит.
REST API: минимум, который нужно знать новичку
Что такое программный интерфейс приложения (API)
Перед тем, как начать разговор о REST API, давайте вспомним, что такое API и для чего он нужен. API расшифровывается как Application Program Interface — программный интерфейс приложения. Данное понятие применимо не только к веб-разработке, но и к любым программным продуктам вообще. Наушники, микроволновые печи, телевизоры, микропроцессоры — все они имеют свой API.
Предположим, мы имеем дело с двумя такими совершенно разными разработками, каждая из которых обладает своим собственным API. Эти системы должны как-то взаимодействовать между собой, но есть некоторая сложность — ведь каждая из систем разработана на своем языке, по своим стандартам, со своими драйверами, на своей операционной системе и так далее. Чтобы как-то привести эти системы к общему знаменателю и иметь возможность коммуникации, мы используем API как некие внешние рычаги, которые влияют на внутреннее состояние каждой из систем. По этому принципу работает огромное количество проектов.
REST API — частный случай API
Допустим, мы написали сайт на PHP (Python, Java — не принципиально). PHP генерирует контент на сервере и по сети нам отправляет обратно уже сгенерированный HTML, JavaScript и CSS. Создавая сайт на PHP, вы получили некую статику, напрямую связывая код PHP, стили, HTML. Он взаимодействует с базой данных и выводит данные в шаблон. Предположим, мы задались целью разработать мобильное приложение под данную систему. Мобильное приложение должно работать с той же базой данных и мы должны как-то присоединить его к уже существующей системе.
Раньше многие шли по такому пути — создавали API для системы «сайт плюс база данных», и мобильное приложение работало через API или непосредственно через сам сайт. Но поддерживать и расширять такую концепцию было неудобно, поэтому постепенно перешли к варианту, когда используется связка backend и frontend. Backend по-прежнему работает с базой данных, а frontend является вообще отдельным приложением, которое, грубо говоря, ничего не знает про backend. Frontend является абстрагированный клиентом и может быть написан на Angular, React, Vue или просто на JavaScript.
Если для сайта имеется мобильное приложение, оно также относится к разряду клиентов и общается с backend-частью посредством API. При такой схеме клиентов может быть сколько угодно — мобильный клиент для Android, приложение под iOS, десктопное приложение, админка сайта и т. д. Частным случаем такой организации является REST API (Representational State Transfer) — некий стандартизированный протокол, позволяющий перемещать state и обмениваться им по API. Впервые его описал в своей диссертации Рой Филдинг. В ней он предложил соединять разные части программы либо сервисы по HTTP.
Критерии RESTful-приложения
Rest — это обычный запрос клиент-сервер с использованием HTTP протокола. В роли клиента не обязательно выступает браузер, это может быть мобильное приложение, десктопное приложение или же другой веб-сайт. В качестве ответа сервер выдает не привычную html-страницу, а просто набор данных, оформленных в том или ином формате. Чаще всего это JSON или XML. Неразрывно с REST следует AJAX (Asynchronous Javascript and XML).
Речь идет об отправке с браузера асинхронных запросов к серверу с помощью JavaScript. XML в данном случае не актуален, а процесс асинхронного общения браузера и веб-сервера задается именно REST-правилами. Веб-сервисы, которые полностью соответствуют парадигме Representational State Transfer, обычно называются RESTful. Чтобы приложение было RESTful, оно должно удовлетворять следующим правилам:
SOAP API — стандарт–предшественник REST API
Хотя на REST API и накладываются эти ограничения, он считается более простым в использовании, чем предшествующий ему протокол SOAP (простой протокол доступа к объектам). Последний выдвигает определенные требования, такие как обмен сообщениями XML, а также встроенные средства безопасности и соответствия транзакциям, что делает его медленнее и тяжеловеснее.
При отправке запроса данных в SOAP API, данные могут обрабатываться через любой из протоколов прикладного уровня: HTTP (для веб-браузеров), SMTP (для электронной почты), TCP и прочие. SOAP использует HTTP как транспортный протокол, в то время как REST базируется на нем. Как только запрос получен, возвращаемые сообщения SOAP должны быть переданы в виде XML-документов — языка разметки, который может считываться как человеком, так и машиной. Завершенный запрос к SOAP API не кэшируется браузером, поэтому он не может быть доступен вторично без повторной отправки в API. На данный момент SOAP — это устаревший стандарт, тем не менее довольно часто используемый enterprise-системами.
Типы запросов
Благодаря тому, что REST API построен поверх HTTP, не важно на каком языке написан frontend (JavaScript или Swift) и backend (Python, Java, C# и пр.), все они смогут взаимодействовать с данным протоколом. Каждый ресурс в REST должен быть идентифицирован посредством стабильного идентификатора, который не меняется при изменении состояния ресурса. Идентификатором в REST является URI. При помощи URL REST API сервер понимает с какими объектами работает, какие объекты ему нужно получить и какие объекты следует удалить.
REST API активно использует методы HTTP протокола и его статуса. В нем присутствуют несколько основных типов запросов:
Если мы говорим о REST как о бизнес-логике, то у нас есть объект и мы передаем статус этого объекта. Например, у нас есть сайт пиццерии и новый заказ. Мы можем заказ создать, узнать о нем подробности, можем обновить его или удалить. И чаще всего для этого используется формат JSON.
Коды запросов
Структура запроса включает в себя маршрут запроса, тип метода, заголовки и тело сообщения. Каждый запрос REST API сопровождается цифровыми кодами. Такие коды называются HTTP-статусами. Они сообщают об успешности запроса.
Статусы разделены на пять групп по своему значению:
Например, редактирование записи на сервере может выполнено успешно (код 200), может быть заблокировано контролем безопасности (код 401 или 403), или не пройти вообще из-за ошибки сервера (код 500).
Чтобы работать с REST API сервисами можно использовать такие инструменты как Postman, SOAP UI (open source утилита по работе с сервисами) и Curl — утилита командной строки, присутствует почти на всех Linux-компьютерах.
Недостатки REST API
Минус этого архитектурного стиля состоит в том, что он завязан на HTTP. Спецификация HTML имеет ограничения и формы, отправляющие данные могут быть реализованы только через GET или POST. Поэтому для корректной работы с другими методами их приходится имитировать. Например, в Rack (механизм на базе которого Ruby взаимодействует с веб-сервером; с использованием Rack сделаны Rails, Merb и прочие Ruby-фреймворки) в форму можно прописать hidden-поле с именем “_method”, а в качестве значения указать имя метода (скажем, «PUT») — при этом будет отправлен POST-запрос, но Rack сможет сделать вид, что получил PUT, а не POST.
Заключение
Теперь вы знаете, что такое REST API и где он применяется. Если говорить понятными словами — это возможность сервера давать доступ клиенту к своим ресурсам. Главный плюс REST API — его простота. Обращение REST API мало чем отличается от обычного запроса к веб-сайту (с небольшим расширением и описанием набора правил, как эти запросы будет происходить).
Недостатком REST API является то, что он опирается на спецификацию HTTP-протокола. Сам по себе REST API не является стандартом, это архитектурный подход. Из этого следует, что он может сильно отличаться у разных компаний. REST удобно использовать в простых случаях и когда важна скорость работы — при работе с мобильным устройством, с JavaScript. В сложных случаях, когда критична поддержка валидации, транзакции — используется SOAP. Помимо REST API имеются и иные способы создания API-систем, такие как JSON-RPC, XML-RPC и GraphQL. Однако на данный момент архитектурный стиль REST API остается самым популярным.
Детальное описание всех кодов REST-запросов (справочник) можно найти здесь — https://restapitutorial.ru/httpstatuscodes.html
Подробнее о REST-проектах, построенных с применением данного архитектурного стиля, а также их отличиях от SOAP сервисов можно узнать из видео ниже: