УСПОКОИТЕЛЬНАЯ документация API [закрывается]

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

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

Один URI, чтобы управлять ими всеми

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

Псевдоним - это ваш URI

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

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

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

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

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

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

Dynamic distribution

Dynamic distribution

It is not just the path part of the URI that you can change. Вы также можете изменить хост. Представьте, что ваше приложение начинает получать гораздо больше использования, чем вы ожидали, вы можете легко изменить хост всех графических или видео ресурсов, чтобы указать на другой сервер. Вы даже можете обеспечить простую балансировку нагрузки, возвращая различные хосты. Так как RESTful API не имеют никакого значения, не имеет значения, какой сервер ответит на запрос. Эта функция полезна для многих сценариев: перемещение HTTPS вещей на выделенный сервер, географическое распределение запросов в зависимости от местоположения клиента, вертикальное разбиение функций приложения на разные серверы.

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

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

Невозможно автогенерировать интересные вещи

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

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