Документация API RESTful

Я собираюсь разработать RESTful API в ближайшее время, поэтому мне нужно описать его, чтобы позволить другим людям начать внедрение клиентов, используя его.

Я немного оглянулся, но, к сожалению, я не нашел стандартизованной формы описания веб-сервисов RESTful. То, что я ищу, похоже на JavaDoc, хотя его не нужно генерировать из какого-либо кода. Я также не говорю о чем-то вроде WADL, я скорее хочу получить какую-то удобочитаемую документацию, которую я могу раздавать.

В связи с природой веб-сервисов RESTful стандартизировать документацию должно быть довольно просто. Он должен просто перечислять доступные ресурсы, соответствующие URI, разрешенные методы, типы контента и описывать доступные действия. Есть ли у вас какие-либо предложения?

Спасибо заранее и приветствует

Ответ 1

В связи с природой веб-сайта RESTful услуг, должно быть довольно легко стандартизировать документацию. Должно просто перечислите доступные ресурсы, соответствующие URI, допустимые методы, типов контента и описать доступные действия. У вас есть предложения??

Это абсолютно неправильный способ документировать услуги REST.

Один URI для управления всеми ними

Вы никогда не должны перечислять URI ресурсов, поскольку это побуждает клиента жестко кодировать эти URI в код клиента. Это создает ненужную связь между клиентом и сервером. URI следует открывать на основе навигации из корневого URI-сервиса. Корневой URI является единственным URI, который должен быть документирован. Документация должна быть сосредоточена на описании информации и ссылок в возвращаемых представлениях. Если вы начинаете с представления, которое возвращается из корневого URI, вы можете описать тип носителя и ссылки, которые могут быть предоставлены в этом документе.

Псевдоним ваших URI

Важно использовать какой-то псевдоним, чтобы создать слой косвенности между клиентом и сервером. Если вы следуете стандарту atom: link для определения ссылок, атрибут rel становится идентификатором. Однако существуют и другие способы определения ссылок, например, способы встраивания изображений в html. Идентификатор изображения может иметь идентификатор и href. Тег идентификатора должен использоваться для идентификации изображения, к которому вы хотите получить доступ к URL-адресу.

Типы носителей определяют ваш API

Конечным результатом является то, что вы определяете все конечные точки в вашем API в контексте некоторого представления. Полный API определяется набором возвращаемых представлений и связями, которые их соединяют.

Итак, вы можете спросить, какая разница? Почему бы просто не создать список конечных точек? Вот несколько причин,

Изменение пространства URI

Поскольку эти ссылки доступны клиенту с использованием псевдонима, это позволяет полностью изменить структуру URL вашего сайта, не затрагивая клиента. Это делает все бесконечное "то, что является наилучшим способом структурирования моего иерархического URL", вопросы, которые в значительной степени несущественны. Вы можете попробовать это в одну сторону, и если это не сработает, просто измените его, вы не сломаете какой-либо клиентский код или не должны будете менять какую-либо документацию!

Динамическое распределение

Это не просто часть пути URI, которую вы можете изменить. Вы также можете изменить хост. Представьте, что ваше приложение начинает получать гораздо больше ресурсов, чем вы ожидали, вы можете легко изменить хост всех графических или видеоресурсов, чтобы указать на другой сервер. Вы даже можете обеспечить простой баланс нагрузки, возвращая разные хосты. Поскольку API-интерфейсы RESTful являются апатридами, на самом деле не имеет значения, какой сервер отвечает на запрос. Эта функция полезна для многих сценариев: перемещение материала HTTPS на выделенный сервер, географическое распределение запросов на основе расположения клиента, вертикальное разделение функций приложения на разные серверы.

Явный протокол

Просто потому, что представление может вернуть ссылку, это не значит, что оно всегда будет. Сервер может возвращать только ссылки, которые разрешены на основе текущего состояния ресурса. Это может быть очень полезно, когда есть определенный протокол, который необходимо соблюдать при взаимодействии с ресурсом сервера. Клиентский код не должен понимать правила протокола, он может просто предоставить пользователю ссылки, которые были предоставлены сервером.

Вы не можете автогенерировать интересный материал

Причина, по которой большинство автоматизированных усилий по документированию служб REST неэффективна, объясняется тем, что единый интерфейс устраняет необходимость документировать простые вещи. Как только вы понимаете HTTP (см. RFC2616), вы понимаете всю механику API. Все, что осталось, - это действительно интересная информация о конкретном домене, которая не может быть сгенерирована.

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

Ответ 2

Нет никаких стандартных, просто открытых дебатов. В InfoQ есть интересная статья: Описание приложений RESTful.

Ответ 3

Если вы используете что-то вроде JAX-RS, вы можете использовать фактический JavaDoc реализации как свою ссылку. Или делать сканирование аннотаций и генерировать его автоматически тоже не должно быть слишком сложно, хотя я не знаю конкретной реализации.

Ответ 4

Если вы используете шаблон MVC, URL-адрес обычно представляется как:

example.com/class/function/ID

Это прагматичные доступные части информации, что означает, что вы все равно можете использовать JavaDoc и иметь возможность документировать подход RESTful, поскольку каждая часть URL-адреса связана с самим исходным кодом.