REST-service контракт?

Question

[1nd1go]

Приветствую!


Мучает вопрос о контракте REST-сервисов. О нем (о контракте), почему-то никогда не говорится. Если в случае с SOAP или подобными web-сервисами есть какой-то WSDL, по которому можно определить какие данные ходят и какие операции поддеркуживаются с какими запросами, то в REST'е такого нет (не будем говорить о WADL, потому что очень многие считают его заведомо мертвым). Более того, в случае с SOAP, часто применяется WSDL-first, когда сначала определяется контракт, а потом реализуется сервис.


Это понятная вещь при создании сервисов.


На одной конференции я пытался узнать про контракт REST-сервисов, и мне сказали, что в этом случае все не так и мы при запросе получаем список доступных операций. При этом контракта на приходящие данные, структуру их нет.


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


Не могу понять с какой только, не подскажите?

Comments

[1nd1go]

Как вообще документацию правильно писать на REST сервис

Answer 1

[spbcypher]

Настоятельно советую книгу RESTful Web Services Cookbook- Solutions for Improving Scalability and Simplicity — очень хорошо о ресте, + там также рассмотрен вопрос документирования (там предлагается использовать метод HTTP OPTIONS)

Answer 2

[png]

Вообще-то есть WADL
Аналог WSDL для REST.
Ссылка про то как он нужен и важен.

Спек, где про него можно почитать.

И ещё в догонку — прикольный веб-сервис, позволяющий создать такой файл.

Есть так же библиотеки под разные языки, которые позволяют создавать такой файл автоматизированно.

На практике, протокол REST очень прост, просто проще SOAP. Поэтому описанием WADL часто пренебрегают. Но если он есть, то им очень удобно пользоваться.
Например, JetBrains Idea умеет генерить из WSDL/WADL файла набор java-классов, которыми уже можно пользоваться, чтобы работать с протоколом.

Comments

[png]

REST прост — я имел в виду, сделал обработку POST/GET/PUT запроса, разобрал урл, выдал в ответ XML или JSON и всё. Заморачиваться с генерацией каких-то XML никто не хочет.
Ну и к сожалению, зачастую, просто не знают об этом.

[1nd1go]

Да, так вот WADL — это как раз попытка перенести достаточно жесткую концепцию SOAP сервисов на REST. И это неправильно. Вот неплохой ответ: stackoverflow.com/questions/1966243/restful-api-documentation.

[png]

Ответ в stackoverflow интересный. Спасибо.
Если относиться к REST как к протоколу над HTTP, то так оно и есть.
Если думать о разработке и об автоматизации разработки, то:
ИХМО, WADL не делает никаких ограничений, как WSDL, вы просто в стандартизированной форме сообщаете клиенту о том, что у вас такого бывает, это удобно для автоматизированных генераторов и не более.