REST API

— неоднозначная тема, по которой часто много вопросов и споров. В этом посте кратко расскажу, что такое REST API и как он связан с REST. И самое интересное — покажу принципы REST API на реальных примерах.

Начнём сначала.

REST — это набор архитектурных принципов, которые описал Roy Fielding в диссертации 2000 года. Один из тезисов гласит, что взаимодействие между системами должно крутиться вокруг понятия ресурса.

REST API, в свою очередь, это набор рекомендаций для API: как составить URL-ы, что они принимают и возвращают. От REST здесь берётся только понятие ресурса. Остальное — частные интерпретации, в оригинальном документе ничего этого нет.

Под REST API обычно понимают следующий набор правил:

1️⃣ В основе пути — существительное во множественном числе

❌ https://www.youtube.com/watch?v=123
✅ https://rutube.ru/video/123

Множественное число встречается чаще, но на мой взгляд единственное тоже ок. Главное, чтобы в рамках проекта был единый стиль, и не смешивалось единственное и множественное

2️⃣ Иерархия ресурсов отражается в URL

Например, в магазине одежды есть раздел с футболками. Как это отразить в API:
❌ https://www.lamoda.ru/c/2478/clothes-futbolki/
✅ https://www.sportmaster.ru/catalog/zhenskaya_odezhda/futbolki/

3️⃣ Желаемые действия с ресурсом определяются через HTTP методы

Искусственный пример:
▫️ GET /users — вернуть список всех пользователей
▫️ GET /users/5 — получить пользователя с id=5
▫️ POST /users — добавить пользователя
▫️ PUT /users/5 — обновить пользователя с id=5 целиком
▫️ PATCH /users/5 — обновить часть полей у пользователя с id=5

Найти идеальный реальный пример у меня не получилось, но очень близок оказался HeadHunter API по работе с резюме. Там всё по канону, но для редактирования они используют PUT.

4️⃣ Вызов методов GET, DELETE, PUT, PATCH должен быть идемпотентным

Чтобы без проблем вызвать метод повторно, если что-то пошло не так

5️⃣ Методы PUT, POST and PATCH возвращают новый/обновлённый объект

6️⃣ Дополнительные параметры для метода GET указываются через ?, а тело метода остаётся пустым

GET /resumes?text=java&age_from=18 – поиск совершеннолетних кандидатов, в резюме которых встречается "java"

7️⃣ Информация для POST, PUT, PATCH запросов передаётся в теле метода

8️⃣ В качестве ответа возвращается соответствующий HTTP код
▫️ 1хх: информационные сообщения, чаще всего служебные. Для бизнес-логики не используются
▫️ 2xx: всё супер
▫️ 3xx: redirect
▫️ 4xx: ошибка на стороне клиента
▫️ 5xx: ошибка на стороне сервера

Какие плюсы у REST API?

Плюс на самом деле только один — в таком API проще разобраться. У Stepik REST API нет документации, но и так понятно, что GET /api/courses возвращает список курсов.

Как видно по примерам выше, некоторые компании придерживаются подобных правил, некоторые — нет. Rutube более REST API, чем Youtube, но для успеха продукта этого явно недостаточно🤭