Что такое REST API и почему ваш, скорее всего, им не является

Вы называете свой API RESTful? Поздравляю, вы не одиноки. Почти каждый второй разработчик на собеседовании утверждает, что его API соответствует принципам REST. Но давайте честно: чаще всего это просто CRUD с JSON-обёрткой, завернутый в красивую документацию.

REST — это не про JSON

Главный миф: REST = HTTP + JSON. На самом деле REST (Representational State Transfer) — это архитектурный стиль, предложенный Роем Филдингом в 2000 году. Его ключевые принципы: единообразие интерфейса, отсутствие состояния (stateless), кеширование, клиент-серверная архитектура и другие. Если ваш API не соблюдает хотя бы половину из них — это не REST, а просто HTTP API.

Признаки, что ваш API — самозванец:

• Вы используете глаголы в URL (/getUser, /deleteItem). REST предполагает, что действия определяются HTTP-методами (GET, POST, PUT, DELETE), а URL — это ресурсы (существительные).
• Вы не используете HATEOAS (Hypermedia As The Engine Of Application State). Да, это страшная аббревиатура, но без неё ваш API не является RESTful в полном смысле. Клиент должен уметь навигировать по API через ссылки в ответах, а не через документацию.
• У вас есть сессии на сервере. REST требует stateless — каждый запрос должен содержать всю информацию для его обработки. Иначе вы получаете «REST с состоянием», что оксюморон.

Почему это важно?

Потому что REST — это не про моду, а про масштабируемость и простоту поддержки. Нарушая принципы, вы получаете хрупкий API, который сложно кешировать, тестировать и развивать. А когда приходит новый разработчик, ему приходится разбираться в вашей «уникальной» интерпретации REST.

Комментарий студии METABYTE

Мы тоже когда-то называли свои CRUD-контроллеры REST API, но быстро поняли: лучше честно признаться, что это просто HTTP API, чем потом краснеть перед Роем Филдингом. Если хотите построить настоящий RESTful сервис — мы поможем, но предупреждаем: HATEOAS кусается.