Примеры сервисов REST в машиночитаемом [закрытом] формате

Следующее является моим личным мнением:

Я думаю, что WADL похож на карты сайта для html-страниц. Карты сайта считаются теоретически хорошей практикой, но редко реализуются и еще реже используются людьми.

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

Методы REST API не должны требовать формального описания. Таким образом, если API создается вдумчиво, довольно легко обнаружить все ресурсы, просто следуя стратегически размещенным ссылкам uri «домашнего» ресурса RESTful.

Здесь есть феноненон из курицы / яйца. WADL бесполезен без инструментов, которые его производят или потребляют. Инструменты бесполезны, если сайты не публикуют WADL. и т.д.

У меня модель Amazon работает нормально. В зависимости от вашей аудитории вы получите большую отдачу от усилий по созданию образцов, включая фрагменты диалоговых окон образцов (как выглядит запрос 1 в сети, то же самое для ответа 1, затем запроса 2, ответа 2 и т. Д.) И кода в vvarious языки, которые важны для вас. Если вы хотите перейти к машиночитаемому определению, вы можете использовать XSD, если это формат сообщения XML. Очевидно, это не WADL, но в сочетании с вашим описанием на английском языке он может предоставить разработчикам дополнительную полезность.

В чем преимущество машиночитаемого определения REST API?

Смысл REST в том, чтобы API был относительно простым и понятным. Для этого хорошо подходит естественный язык.

Если вы имеете в виду «Определения типов API», когда говорите «Определение API», то предоставление метаданных может иметь некоторую ценность. Однако это только одна часть определения API.

Наличие «машиночитаемого» API может легко повторять исходный код API, нарушая принцип DRY.

Часто проще написать английское описание того, что глаголы REST делать и каковы URI. Отправьте типы, упорядоченные через JSON (или YAML, или JAXB), в качестве исходного кода. Это идеальный машиночитаемый API - фактический рабочий источник для класса объекта сообщения.

Да, стоит. Вы сможете генерировать клиентский код, тесты и документацию с помощью набора инструментов, поддерживающих WADL. Некоторые примеры можно найти здесь . Также, я думаю, что вы должны придерживаться WADL, а не WSDL 2.0, потому что она менее многословна и намного проще (IMHO). На самом деле, в WADL вы описываете именно то, что пользователь видит на странице документации, просто используя синтаксис WADL XML. BTW, вот почему так просто написать генераторы документации на основе XSLT для WADL.

Самым популярным использованием WSDL (и WADL аналогичным образом) является генерация кода. Это, безусловно, помогает ускорить разработку, но ничто не может заменить старую простую документацию. Для людей, а не для машин.