aspose file tools*
The moose likes Web Services and the fly likes Contract for REST services Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Java » Web Services
Bookmark "Contract for REST services" Watch "Contract for REST services" New topic
Author

Contract for REST services

Thillai Sakthi
Ranch Hand

Joined: Jun 17, 2000
Posts: 102
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 !


Regards,
Shakthi
Ulf Dittmer
Marshal

Joined: Mar 22, 2005
Posts: 41867
    
  63
Well, there's WADL, which some REST implementations (like Jersey) support. It's sort of the REST equivalent to WSDL.


Ping & DNS - my free Android networking tools app
William Brogden
Author and all-around good cowpoke
Rancher

Joined: Mar 22, 2000
Posts: 12788
    
    5
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

Joined: Jan 10, 2002
Posts: 61221
    
  66

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.


[Asking smart questions] [Bear's FrontMan] [About Bear] [Books by Bear]
James Boswell
Bartender

Joined: Nov 09, 2011
Posts: 1021
    
    5

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

Joined: Jan 10, 2002
Posts: 61221
    
  66

Interesting...
Thillai Sakthi
Ranch Hand

Joined: Jun 17, 2000
Posts: 102
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
Marshal

Joined: Mar 22, 2005
Posts: 41867
    
  63
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

Joined: Jun 17, 2000
Posts: 102
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
Marshal

Joined: Mar 22, 2005
Posts: 41867
    
  63
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

Joined: Nov 09, 2011
Posts: 1021
    
    5

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.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Contract for REST services