Советы по REST API

Будь то RESTful или нет (в соответствии с шестью ограничениями, описанными ранее), вот несколько рекомендованных REST концепций, которые помогу построить более лучшие и удобные сервисы:

Используйте HTTP Глаголы для Обозначения Чего-либо

Любой пользователь API способен присылать GET, POST, PUT и DELETE глаголы, которые значительно повышают ясность того, что делает запрос. Также, GET запрос не должен изменять любые базовые данные ресурса. Измерение или отслеживания, которые обновляют данные, а не данные URI, могут происходить.

Рациональное название ресурсов

Рациональное название ресурсов или путей (т.е., /posts/23 вместо /api?type=posts&id=23) улучшает ясность того, что делает запрос. Использование параметров строки запроса - это очень хорошо для поиска и фильтрации данных, но плохо для имен ресурсов.

Подходящие названия ресурсов предоставляют контекст для запроса и делают API сервиса более понятным. Ресурсы рассматриваются иерархически через их имена URI, предлагая клиентам простую иерархию ресурсов для достижения цели в своих приложениях.

Имена ресурсов должны быть существительными - избегайте глаголов в качестве имен ресурсов. Это дает больше ясности. Чтобы указать глагол в запросе, используйте HTTP методы.

XML и JSON

Предпочтительна поддержка json, но если цена между поддержкой JSON и XML не велика, то можно использовать оба. В идеале, пусть потребители переключаются между ними, просто изменив расширение из .xml в .json. Кроме того, для поддержки пользовательских интерфейсов в стиле AJAX, обернутый ответ может быть очень полезным. Обеспечивайте обернутый ответ по умолчанию или для отдельных расширений, таких как .wjson и .wxml, чтобы указать, что клиент запрашивает обернутый JSON или XML запрос.

JSON, как стандарт, имеет мало требований. И никаких требований о формате содержимого или макета, только о синтаксисе. Другими словами, JSON ответ на вызов REST сервиса не описан в стандарте и является договорным. Больше о формате данных JSON можно найти на http://www.json.org/.

Что касается использования XML в сервисах REST, стандартов и конвенций действительно не существует, кроме использования синтаксически правильных тегов и текстов. В частности, пространства имен не используются, и не должны быть использованы в контексте RESTful сервисов. Возвращаемый XML больше похож на JSON и просто читается, без схемы и пространства имен - представлены только данные и ссылки. Если в конечном итоге все сложнее, прочитайте еще раз первый параграф этой подсказки — цена XML слишком велика. Если судить по нашему опыту - никто никогда не отвечает в формате XML. Обрабатывать XML слишком затратно.

Создавайте детальные Ресурсы

Сначала гораздо проще создавать API, которые имитируют основной домен приложения или архитектуру базы данных вашей системы. В конце концов, вы хотите объединить сервисы, которые используют несколько основных ресурсов, чтобы избежать избыточности информации. Но позже гораздо проще создать большие ресурсы из отдельных ресурсов, чем детальные ресурсы от более крупных агрегатов. Легко начать с маленьких, легко определяемых ресурсов, обеспечивая функциональность CRUD. Ресурсы без лишней информации, ориентированные на конкретные ситуации, можно сделать позже.

Учитывайте связность

Одним из принципов REST является связность через ссылки. В то время, когда сервисы остаются полезными без них, API становится более самоописательным, когда ссылки содержатся в ответе. По крайней мере, ссылка "на себя" информирует клиентов, как данные были или могут быть восстановлены. Кроме того, используйте заголовок Location для содержания ссылки на создание ресурса через POST. Для коллекций возвращайте в ответе сведения о том, что поддерживается пагинация, 'первый', 'последний', и 'предыдущий' ссылки. Это очень полезно.


Fork me on GitHub