Post #253

Про REST слышали наверняка все. Некоторые даже слышали про RESTful. Единицы вспомнят модель зрелости REST Леонарда Ричардсона и её уровни. Между тем, есть отличная статья Guy Levin, перевода которой я почему-то не нашел. Нужно это срочно исправить! Здесь дам короткий вольный пересказ. Уровень 0: The swamp of POX (Plain old XML) — Болото старого доброго XML. Это нам напоминает, с чем боролся Рой Филдинг: XML, SOAP и вызовы разных функций из одного эндпоинта методом POST. Даже тут есть правила: 1. В названиях эндпоинтов слова нужно разделять дефисом: "-", это spinal case или kebab-case, "шашлычный стиль" — слова как бы нанизываются на шампур. 2. Подчеркивания в названиях эндпоинтов лучше не использовать. Почему так: потому что ссылки в тексте подчеркиваются, и символы "_" могут визуально потеряться, в отличие от "-". 3. Все ссылки должны быть в нижнем регистре. Это всё рекомендации RFC3986. 4. Расширения (то есть точку) лучше не использовать, формат ответа задаётся заголовком Content-Type. Пример: http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post Уровень 1. Ресурсы. Идея: разные эндпоинты для разных ресурсов. Названия эндпоинтов - существительные. Правила: 1. Слэш ("/") в конце названия эндпоинта не нужен. Каждый ресурс имеет один адрес (URI). Разные URI указывают на разные ресурсы. 2. Слэш употребляется для указания иерархии ресурсов: http://api.canvas.com/shapes/polygons/quadrilaterals/squares, http://api.college.com/students/3248234/courses/2020/fall 3. Существительные в единственном или во множественном числе? Тут у автора сомнения, но большинство фреймворков поддерживают названия ресурсов во множественном числе. Мне лично тоже больше нравится во множественном. Уровень 2. Методы. Используем для операций с ресурсами стандартные методы http, соответствующие CRUD: POST, GET, PUT, DELETE, PATCH + дополнительные HEAD и OPTIONS. Если вам не хватает операций CRUD, автор рекомендует сделать подчиненный ресурс /actions, и делать к нему POST с указанием типа операции и дополнительных параметров. Такой небольшой кусочек RPC-like style, когда RESTful не одобряет, но очень хочется. 2.1. Заголовки HTTP Используйте заголовки! Тема тут обширная, но в основном заголовки используются для безопасности, переговоров клиента и сервера о форматах и кодировках контента, о кэшировании, версиях и обновлениях ресурсов, их размерах. Собственно, запрос HEAD возвращает заголовки без самого тела ресурса, чтобы клиент мог понять — нужно ли запрашивать ресурс вообще. 2.2. Параметры запроса Используйте параметры запроса! (та часть, которая после @?"). Не забывайте про такие операции, как фильтрация, поиск, сортировка и пагинация. Для фильтров добавляем названия полей ресурса, по которым можно отфильтровать результат, указав значения или диапазон: https://example.com/api/products?category=electronics&price=50-100 Для поиска — параметр ?q={строка поиска}. Для сортировки: ?sort={поле, по которому сортируем}&order={ASC|DESC}. Как вариант, для сортировки по нескольким полям: ?sort=name,-price (сортируем по названию в прямом порядке, по цене — в обратном). Для пагинации указываем число элементов на странице и номер страницы: ?limit=10&offset=20. 2.3. Коды ошибок Используйте коды ошибок HTTP. Уровень 3. Управление гипермедиа. Тут два аспекта: обсуждение формата и HATEOAS. 3.1. Обсуждение формата — это про заголовки. Клиент и сервер договариваются, в каком формате сервер вернет ресурс. Может, в json, может в XML, а может просто в виде текста. В теории должно работать, и серверы должны отдавать ресурс в удобном для клиента представлении. На практике реализация встречается очень редко, но во внутренних гетерогенных системах может быть полезным. Запрос OPTIONS как раз про это: какие действия допускает сервер над ресурсом и в каких форматах готов его отдавать.