Should I describe REST services in a machine readable format?

Question

Most REST interfaces I see are described with a simple web page describing the URL, the method, accepted input and returned result. For example the Amazon S3 or the Twitter API documentation.

But why should I settle with what is apparently good enough for Amazon or Twitter... So, is it worth describing a REST API in a machine readable format? And if yes, which one?

WSDL 2.0 claims is capable of describing REST. WADL is explicitly created for describing REST services. Both WSDL 2.0 and WADL seem to have a rather small following atm and it seem to be little return for the effort of creating and maintaining the description documents. My uestion is basically to validate or negate my assumption.

Do you use WSDL/WADL to describe your services? Do you rely on WSDL/WADL to consume others' services? Does your tool of choice support either one at the moment?

Answer 1

The following is just my personal opinion:

I think WADL is similar to site maps for html pages. Site maps are considered theoretically a good practice, but rarely implemented and even more rarely used by people.

I think the reason is simple - wandering around a site and pushing strategically placed buttons is often significantly more rewarding than browsing a complex map.

REST API methods should not require a formal description. So if API is created thoughtfully it is pretty easy to discover all the resources just by following strategically placed uri links of a 'home' RESTful resource.

Answer 2

What is the benefit of a machine-readable REST API definition?

The point of REST is for the API to be relatively simple and easy-to-understand. Natural language works well for this.

If you mean "API Type Definitions" when you say "API Definition" then there may be some value in providing metadata. This, however, is only one piece of an API definition.

Having "machine readable" API can easily repeat the API source code, violating the DRY principle.

It's often simpler to write English descriptions of what the REST verbs do and what the URI's are. Send the type's which are marshalled through JSON (or YAML or JAXB) as source code. That's the perfect machine-readable API -- actual working source for the message object class.

Answer 3

There's a chicken/egg phenonenon here. WADL is useless without tools that produce or consume it. The tools are useless unless sites publish WADL. etc.

For me, The Amazon model works fine. Depending on your audience you will get more return on an effort to produce samples, including snips od sample dialogs (what does request1 look like on the wire, same for response 1, then request 2, response 2, etc), and code in vvarious languages that are important to you. If you want to go to a machine-readable definition, you can use XSD if it is an XML message format. Obviously this is not WADL but coupled with your english description, it may provide a little extra utility for developers.

Answer 4

Yes, you should. You will be able to generate your client code, tests and documentation using a set of tools supporting WADL. Some examples can be found here. Also, I think you should stick with WADL, rather than WSDL 2.0 because it is less verbose and way simpler (IMHO). In fact, in WADL you describe exactly what the user sees on the documentation page, just using WADL XML syntax. BTW, that is why it's so easy to write XSLT-based documentation generators for WADL.

Answer 5

The most popular usage of WSDL (and WADL in the same way) is code generation. It sure helps speed up development, but nothing can replace plain old documentation. For humans and not for machines.