Недавно мне сообщили, что надлежащий RESTful API должен определять схему для представлений ресурсов, которые он принимает и возвращает. Например, XSD для XML и JSON Schema для JSON.
Однако во всех книгах и статьях о REST, которые я пережил, это никогда не казалось не только заметным, но даже упоминаемым.
Может ли кто-нибудь предоставить некоторые авторитетные ресурсы, чтобы выяснить, следует ли предоставлять схему при разработке API RESTful?
Вы должны определить и передать интерфейсы запросов и ответов в свой RESTful API как-то, чтобы вызывающие пользователи знали, чего вы ожидаете в запросе, и что они могут ожидать в ответ.
Используете ли вы схему (XSD, JSON Schema и т.д.) или какую-либо другую форму (естественный язык, примеры и т.д.) или какую-либо комбинацию для интерфейсы вам решать. Вот несколько факторов, чтобы сообщить ваше решение:
Насколько хорошо известно соглашение, которое вы будете использовать.
Схема: XSD - стандарт W3C, используемый во многих отраслях; JSON Schema - известная альтернатива XSD для JSON.
Другое: Естественный язык и примеры жизнеспособны и очень полезны, хотя часто неоднозначны или неполны.
Какая конвенция будет лучше всего оценена вашим сообществом.
Схема: XSD особенно особенно ценится сообществами, которые уже инвестировали в разработку стандартных XSD для своей отрасли.
Другое: Природный язык и примеры, как правило, оцениваются новичками.
Как можно автоматизировать процесс проверки, который вы будете использовать.
Схема: Как XSD, так и JSON Schema предлагают встроенную автоматическую проверку.
Другое: Естественный язык и примеры требуют специальных усилий для проверки.
Как плотно или слабо напечатанный интерфейс, который вы будете использовать.
Схема: XSD и JSON могут выражать диапазон специфичности типов, но блестят, когда желательна подробная специфика типа.
Другое: Естественный язык и примеры могут передавать требования к типу, хотя часто неточно.
Наконец, обратите внимание, что вы будете принимать дальнейшие решения, чтобы сделать вне схемы и не-схемы:
Все это важные части сообщения вашего REST API для вызывающих абонентов вашей службы в дополнение к решению схемы и другому решению определения интерфейса.
Вы должны задокументировать свой RESTful API для тех, кто его использует. Схема более специфична для каждого возвращаемого формата данных, что может быть полезно. Вот примеры ссылок API, которые хорошо описывают методы и формы ответов:
API геокодирования Google Maps (JSON и XML)
Справочник по API-интерфейсу SoundCloud
Документация API CloudFlare v4
В основном то, что я вижу, это методы запроса, задокументированные приведенными примерами ответов, и диаграмма, объясняющая, чего ожидать (не так часто формальная схема сама по себе). Сделайте это разумным для людей.
Они являются необязательными. Если вам нужна мелкозернистая фильтрация пользовательских запросов с учетом как синтаксиса, так и семантики содержимого, вы его используете.
https://tools.ietf.org/html/rfc3470
"XML-схема (определенная в [41] и [42]) предоставляет дополнительные функции, позволяющие более плотную и точную спецификацию допустимых синтаксисов протокола и спецификаций типа данных."
"JSON Schema предоставляет контракт на то, какие данные JSON необходимы для данного приложения и как взаимодействовать с ним. Схема JSON предназначена для определения валидации, документации, навигации по гиперссылкам и управления взаимодействием данных JSON".
Как вы можете видеть, IETF не принимал это как RFC (это еще черновик). Они думали, что это слишком много для простого протокола, такого как JSON. Однако многие проекты с открытым исходным кодом полагаются на этот проект.