• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Contract for REST services

 
Thillai Sakthi
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
All,

As the REST services do not have a published contract (WSDL), when someone is under discovery process exploring for services that they can re-use, how does he/she locate a REST service and its contract ? SOAP based web services offer WSDL that one can browse through and identify the data fields returned by that service et al. But since REST services are driven off of simple URLs, how to make that determination ? Does one have to look into the code ?

Also, in the absence of a formal contract, how does the consumer and provider come to common terms w/r/t what is expected from each party ?

Thanks !
 
Ulf Dittmer
Rancher
Pie
Posts: 42967
73
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Well, there's WADL, which some REST implementations (like Jersey) support. It's sort of the REST equivalent to WSDL.
 
William Brogden
Author and all-around good cowpoke
Rancher
Posts: 13055
6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I would expect any commercial RESTful service to provide extensive text description and example code.

Recall that REST is an architecture / style - not a messaging API like SOAP.

REST is simultaneously restricted and open ended. Restricted to the use of HTTP methods GET, POST, etc - open ended in that any resource can be returned, not just a XML document like SOAP.

Bill
 
Bear Bibeault
Author and ninkuma
Marshal
Pie
Posts: 64620
86
IntelliJ IDE Java jQuery Mac Mac OS X
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
William Brogden wrote:I would expect any commercial RESTful service to provide extensive text description and example code.

This is exactly what I do.

In fact, I auto-generate the docs from annotations on the code.
 
James Boswell
Bartender
Posts: 1051
5
Chrome Eclipse IDE Hibernate
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I have just completed a project where we used Swagger to generate the docs for our RESTful API. What is great is that it also allows you to execute each operation on the interface.
 
Bear Bibeault
Author and ninkuma
Marshal
Pie
Posts: 64620
86
IntelliJ IDE Java jQuery Mac Mac OS X
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Interesting...
 
Thillai Sakthi
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
William Brogden wrote:

Recall that REST is an architecture / style - not a messaging API like SOAP.

Bill


Bill,

You drove the nail on its head. Thanks !

Also, thinking more about it, the whole purpose of the discovery process is to establish the re-usability of the services in the inventory. So, a human readable document helps the cause even more to make better decisions compared to navigating through WSDLs, which at times stymies developers ! I think the intent then would be how great a document be produced compared to ones that will get generated from sporadic developer comments (akin to javadocs), which may not be at times explaining things clearly.

Swagger looks cool as well.

 
Ulf Dittmer
Rancher
Pie
Posts: 42967
73
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
WSDL and WADL aren't mean't to help with discovery, they're documenting a service in a machine-processable form. That way you can create client-side code for accessing the WS automatically.

The standard for discovering SOAP WS is called UDDI, but after initial enthusiasm, its use has waned to a large degree. There are now no public UDDI directories left that I know of. No comparable standard exists for REST WS.
 
Thillai Sakthi
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yep, I totally agree.

However as UDDI is practically non existent, what is the best way to determine the contractual obligations or to assess the fields to/from the service ?

In my company WSDLs and schemas (more so the latter than the former) are primary means of getting this information. We could use tools such as Ignite XML, but they also pour over schema definitions and WSDLs to extract any meaningful info right ?

Sorry, we deviated a little bit from original intent of the post, but love the discussion nevertheless....
 
Ulf Dittmer
Rancher
Pie
Posts: 42967
73
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Neither WSDL/WADL nor UDDI is a substitute for proper documentation. If that's missing, there isn't much that you can do automatically, besides contacting the author of the WS and getting them to provide the necessary information.
 
James Boswell
Bartender
Posts: 1051
5
Chrome Eclipse IDE Hibernate
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
This is what makes a tool like Swagger (and Bear's suggestion using annotations) so good. Like Javadocs, you can keep your documentation and source code together so that they never diverge.
 
It is sorta covered in the JavaRanch Style Guide.
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic