Examples of REST services in machine readable format [closed]

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.

Human readable is apparently good enough for Amazon or Twitter. However are there any companies describing a REST API in a machine readable format? And if yes, which ones?

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. By identifying real life examples it is basically possible to validate or negate this 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? Are there any examples of broadly used REST services that can be used that are detailed in a machine readable format?

Illfated

See similar question #1312587 – Blackpoll

This question is also relevant: #33776270 – Grattan

Answer 1

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.

Hyssop

Answer 2

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.

Mccully

Your answer is correct in spirit. A REST interface should be discoverable as you describe. However, all media-types used by representations should have formal definitions. REST is not an excuse avoid documenting your API. The difference is what you are documenting. Do document the data structures that flow between the client and the server, just not the endpoints (ie. URLS). – Blackpoll

Answer 3

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.

Shipment

Answer 4

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.

Diphthongize

Machine readable definitions are useful for defining types and other support code in various programming languages. – Gumbotil

Answer 5

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.

Varve