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

В сообщении Роя здесь он заявляет

REST API должен тратить почти все описательные усилия по определению медиа-типы, используемые для представления ресурсы и приложение для вождения состояние, или в определении расширенного имена отношений и / или гипертекстовая разметка для существующих стандартные типы носителей. Любые затраченные усилия описание того, какие методы использовать на чем Интересующие URI должны быть полностью определены в рамках правила обработки для медиа-типа (и в большинстве случаев уже определенные существующими типами носителей).

В моей компании мы очень довольны использованием WADL , язык описания веб-приложений. Википедия описывает как: «формат файла на основе XML, который обеспечивает машиночитаемое описание веб-приложений на основе HTTP». Я считаю, что необработанный WADL легко писать, читать и понимать, и он напрямую соответствует концепциям RESTful. Официальный проект предоставляет простую спецификацию, схемы XSD и RELAX NG и инструменты Java.

Для работы с WADL существует ряд инструментов и ресурсов, в том числе:

• wadl_stylesheets , таблицы стилей XSLT для создания HTML-документации из файлов WADL.
• Restlet , среда Java для создания серверов RESTful и клиентов, включает расширение WADL

. Совет: попробуйте включить удобочитаемую документацию, такую ​​как описания, концепции, начало работы, советы по использованию и т. д., в элемент doc документа WADL, включив элементы HTML, используя пространство имен XHTML. Это может иметь большое значение!

концепции, начало работы, советы по использованию и т. д. в элементе doc документа WADL путем включения элементов HTML с использованием пространства имен XHTML. Это может иметь большое значение!

концепции, начало работы, советы по использованию и т. д. в элементе doc документа WADL путем включения элементов HTML с использованием пространства имен XHTML. Это может иметь большое значение!

Хорошая документация по ReST будет означать документирование вашего типа носителя и только вашего типа носителя.

В типичном сценарии вы создадите такой документ:

XML Acme Corp форматы

Link Discovery

Ссылки на различные ресурсы описаны в документе, который можно найти, отправив запрос GET или HEAD серверу по URI закладки (обычно это корень сервера, http: / /www.acme.org) и ищем заголовок HTTP Link:

Ссылка: ; rel = "http://rel.acme.org/services"; type = application / vnd. acme.services + xml

, где часть rel - это связь, а xxx - это URI, для которого связь была установлена.

Связь ссылок

В этом документе определяется следующие имена отношений:

• http://rel.acme.org/services Связь ссылок описывает список ссылок, по которым можно перемещаться.
• http://rel.acme.org/customers Ссылка, для которой используется это отношение, представляет собой список клиентов.

Типы носителей

application / vnd.acme.services + xml - это документ с xml сериализация, которая описывает список ссылок, которые приложение может захотеть обработать.

<links>
 <link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>

applcation / vnd.acme.customers + xml - это документ с сериализацией xml , который описывает клиентов.

Примеры документов:

<customers>
 <customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>

и т.д ...

Смысл в том, чтобы дать разработчику возможность перейти по указанным вами ссылкам. Сначала найдите ссылку на индекс , чтобы они могли получить список объектов, к которым они могут перейти.

Обнаружив этот документ, они обнаруживают, что могут видеть список клиентов с определенным Uri, и могут применить GET против него.

Если они найдут интересующего клиента, они могут перейти по ссылке, определенной в / customers / customer / @ href , и выполнить GET , чтобы получить представление об этом клиенте.

Оттуда ваш тип мультимедиа может включать действия которые доступны пользователю, используя дополнительные ссылки. У вас также есть дополнительная возможность отправить запрос OPTIONS к ресурсу, чтобы узнать, можете ли вы разрешить удаление ресурса, или PUT, если вы можете сохранить документ обратно после модификации.

Так что хорошей документации никогда не бывает:

• дают статические ссылки
• дают взаимодействие, такое как «вы можете выполнить POST для клиента с этим типом носителя, и это будет означать операцию перемещения». Клиент должен отправить запрос POST против клиента только потому, что ваш XML-документ определил это таким образом.

Смысл всего этого состоит в том, чтобы добиться минимальной связи между клиентами и серверами.