Что такое REST API?

От автора: что такое REST API? REST – это аббревиатура Representational State Transfer или по-русски «передача репрезентативного состояния» — вообще непонятное описание самой используемой технологии в веб-сервисах! REST API – это способ для двух компьютеров взаимодействовать через HTTP в браузерах и серверах.

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

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

REST повсеместно используется в веб-системах для взаимодействия. Например, получение и обновление данных профиля в социальной сети.

Пример REST API

Перейдите по следующий ссылке, в ответ вы получите случайный вопрос по компьютерам с портала Open Trivia Database.

Это публичный API, реализованный как RESTful веб-сервис (следует правилам REST). В браузере отобразится один вопрос с ответом в формате JSON, как на примере ниже:

{ "response_code": 0, "results": [ { "category": "Science: Computers", "type": "multiple", "difficulty": "easy", "question": "What does GHz stand for?", "correct_answer": "Gigahertz", "incorrect_answers": [ "Gigahotz", "Gigahetz", "Gigahatz" ] } ] }

Вы можете выполнить этот запрос и получить ответ в любом HTTP-клиенте, например curl:

curl "https://opentdb.com/api.php?amount=1&category=18"

Библиотеки HTTP-клиентов доступны на всех популярных языках программирования и рантаймах, в том числе Fetch для JS, Node.js и Deno, а также file_get_contents() для PHP. JSON ответ машиночитаемый, т.е. его можно распарсить перед выводом в HTML или другой формат.

REST API и Rest

За последние годы развилось множество стандартов передачи данных. Вы могли слышать про CORBA, SOAP или XML-RPC. Большинство стандартов устанавливают строгие правила передачи сообщений.

REST придумал Roy Fielding в 2000 году. Его подход значительно проще остальных. Это не стандарт, а набор рекомендаций и ограничений для RESTful сервисов. Выделяют следующие правила:

Создание RESTful веб-сервиса

Запрос RESTful сервиса содержит:

Примеры:

Также запрос RESTful сервиса содержит:

REST API ответ

Ответ может содержать все что угодно: данные, HTML, изображений, аудио файл итд. Обычно ответ кодируют в JSON, но бывают ответы в XML, CSV, в виде простых строк итд. Возвращаемый формат можно указать в самом запросе. Например, /user/123?format=json или /user/123?format=xml.

В хедерах ответа также необходимо указать подходящий HTTP статус код. 200 OK используется для успешных запросов, 201 Created можно вернуть при создании записи. У ошибок свои коды, например, 400 Bad Request, 404 Not Found, 401 Unauthorized и так далее.

Другие хедеры можно указать через директивы Cache-Control или Expires. С их помощью можно указать время кэширования.

Тем не менее, нет строгих правил. Эндпоинты, HTTP методы, тело и типы ответов можно реализовывать по-своему. Например, POST, PUT и PATCH часто используют так, что они становятся взаимозаменяемыми и через любой из них можно создать или обновить запись.

Пример Hello World REST API

Node.js код ниже создает RESTful сервис на фреймворке Express. У этого приложения есть один эндпоинт GET /hello/. Установите Node.js, создайте папку restapi. Внутри папки создайте package.json:

{ "name": "restapi", "version": "1.0.0", "description": "REST test", "scripts": { "start": "node ./index.js" }, "dependencies": { "express": "4.18.1" } }

Выполните команду npm install в командной строке, чтобы загрузить зависимости. Далее создайте файл index.js:

// simple Express.js RESTful API 'use strict'; // initialize const port = 8888, express = require('express'), app = express(); // /hello/ GET request app.get('/hello/:name?', (req, res) => res.json( { message: `Hello ${req.params.name || 'world'}!` } ) ); // start server app.listen(port, () => console.log(`Server started on port ${port}`); );

Запустите приложение через командную строку npm start. Откройте в браузере http://localhost:8888/hello/. На экране отобразится JSON:

{ "message": "Hello world!" }

API позволяет передавать имя. То есть запрос на http://localhost:8888/hello/everyone вернет:

{ "message": "Hello everyone!" }

Клиентские REST запросы и CORS

Рассмотрим HTML-страницу ниже, запущенную в браузере по URL http://localhost:8888:

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title>REST test</title> </head> <body> <script> fetch('http://localhost:8888/hello/') .then((response) => { return response.json(); }) .then((json) => { console.log(json); }); </script> </body> </html>

Вызов fetch делает такой же API запрос, а в консоли можно увидеть ответ Object { message: «Hello world!» }.

Предположим, теперь наш RESTful сервис выложили в интернет на реальный домен http://mydomain.com/hello/. URL для fetch изменился. Но если открыть http://localhost:8888 в браузере, мы получим ошибку в консоли Cross-Origin Request Blocked.

По соображениям безопасности браузеры разрешают клиентам выполнять XMLHttpRequest и Fetch API запросы только на тот же домен, откуда идет сам запрос.

К счастью, Cross-origin Resource Sharing (CORS) позволяет нам обойти это ограничение. Заголовок ответа Access-Control-Allow-Origin скажет браузеру, куда он может посылать запросы. В значении можно указать конкретный домен или * для любого домена (как сделано в API из примера выше).

Код API можно изменить, чтобы сервис мог отвечать любому клиенту на любом домене:

// /hello/ GET request app.get('/hello/:name?', (req, res) => res .append('Access-Control-Allow-Origin', '*') .json( { message: `Hello ${req.params.name || 'world'}!` } ) );

Или можно через Express.js middleware функцию добавить наш хедер во все запросы:

// enable CORS app.use((req, res, next) => { res.append('Access-Control-Allow-Origin', '*'); next(); }); // /hello/ GET request // ...

Обратите внимание, что браузеры делают два запроса к REST API:

Чтобы не дублировать код на запрос OPTIONS можно возвращать хедер Access-Control-Allow-Origin с пустым ответом.

Сложности в REST API

Успех REST в его простоте. Разработчики сами пишут RESTful API, как хочется им. Однако это может привести к некоторым сложностям. Для углубленного изучения стратегий архитектуры API ознакомьтесь с нашим уроком «13 лучших практик по созданию RESTful API».

Консенсус по эндпоинтам

Разберем следующие эндпоинты:

Все варианты подходят для получения данных для юзера 123. Количество комбинаций будет расти вместе со сложностью операций. Например, вернуть 10 юзеров, чьи фамилии начинаются на А, и кто работает на компанию Х, начиная с записи 51 с сортировкой по дате рождения в обратном от хронологического порядке.

Абсолютно неважно, как вы будете форматировать URL, однако консистентность во всем API очень важна. В большом проекте, где много разработчиков, это может вызвать некоторые сложности.

Версирование REST API

Изменения в API неминуемы, но нельзя ломать существующие URL. Иначе это приведет к поломке приложения.

Чтобы избежать проблем совместимости, API зачастую устанавливают версию. Например, /2.0/user/123 заменяет /user/123. Оба эндпоинта могут оставаться активными. Такой подход заставляет поддерживать несколько версий API. В будущем старые версии можно удалить, но этот процесс нужно тщательно спланировать.

REST API аутентификация

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

Клиентские приложения в том же домене что и RESTful API будут отправлять и получать куки, как любой другой HTTP запрос. (обратите внимание, что Fetch() в старых браузерах требует credentials init опцию) API запрос можно провалидировать на авторизацию юзера и на наличие подходящих прав пользователя.

Сторонние приложения должны использовать альтернативные способы авторизации. Среди часто используемых способов аутентификации выделяют:

API аутентификация выбирается исходя из контекста:

Безопасность REST API

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

Безопасность выходит за рамки нашей статьи, но можно перечислить общепринятые лучшие практики:

Множественные запросы и ненужные данные

RESTful APIs ограничены лишь реализацией. В ответе может быть больше данных, чем необходимо. Или же для доступа ко всем данным необходимо посылать дополнительные запросы.

Рассмотрим RESTful API, предоставляющим доступ к данным автора и его книг. Для получения данных о топ-10 продаваемых книг клиент может:

Это известная проблема, ее называют проблемой N+1. Для родительского запроса нужно выполнить N API запросов для каждого результата.

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

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

GraphQL фиксит REST API?

Сложные задачки с REST навели на мысль создать GraphQL – язык запросов веб-сервисов. Представьте, что это SQL для веб-сервисов: строка запроса определяет возвращаемые данные и их формат.

GraphQL решает некоторые проблемы RESTful APIs, но и вносит новые сложности. Например, сложнее кэшировать GraphQL респонсы.

Возможно, стоит подумать о GraphQL, когда ваш RESTful API выходит за пределы своего практического применения.

Ссылки по REST API и инструмент для разработки

Существует множество инструментов для разработки RESTful API на всех языках. Выделить можно:

Также есть много публичных REST API для генерации шуток, конвертации валют, геокодирования, получения гос. данных и еще много всего, что сложно представить. Множество из них бесплатны, часть требует авторизации для получения API ключа или для авторизации через другие методы. Списки по категориям:

Перед написанием своего веб-сервиса попробуйте использовать парочку RESTful API в своем проекте. Или последуйте примеру GitHub, Google и других гигантов индустрии и постройте свой RESTful API.

Автор: Craig Buckler

Источник: www.sitepoint.com

Редакция: Команда webformyself.

Читайте нас в Telegram, VK, Яндекс.Дзен