Self documenting REST interface

views:

197

answers:

+5 Q:

Self documenting REST interface

I have a Rails based server running several REST services and a Rails based web UI that interacts with the server using ActiveResource. Same server is being used by other clients( e.g: mobile). I have to generate documentation for the REST interface. I need to provide service URL, input/output and error document structure for each service.

Ideally, I would like to use an interceptor at the server side that will document the service based on the existing traffic. I am wondering if there is a gem to do this.

+1 A:

When you are applying the REST architectural style, you do not need to document your interface.

The contract between client and server is established by the media type used, if you need any other additional documentation, you are not being RESTful.

So, instead of worrying about documenting your service, put all your descriptive effort into the documentation of your media types. Knowledge about media types is all that is necessary to implement the clients for your server.

Jan Algermissen 2010-04-16 06:08:31

Its true that REST services do not need a WSDL like a classic web-service, but they do need a schema. The client needs to know the URL, HTTP method, input document structure, reply structure and error structure for any action. What I am asking for is quite similar to the API documentation that you see for YouTube RESt API, OR Twitter REST API. E.g.: http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-users%C2%A0show

KandadaBoggu 2010-04-16 06:26:00

It can be argued that there is no need to specify HTTP method for a REST service as it can be ingferred from the operation type. But in practice, if you have a custom operation(i.e. non CRUD operation) it is better to document the expected HTTP method.

KandadaBoggu 2010-04-16 06:59:35

Except for an URI to entry the application (there might be many entry URIs, BTW) all of the aspects you mention need to be described by the media type specification. The service needs no description at all. For example, you develop AtomPub clients based on RFC5023, not based on some API description.

Jan Algermissen 2010-04-16 07:31:18

Let us say I am trying to invoke a REST service for creating Order. Do I need to know the schema of the order(resource)? If I do, who gives me this information? If I don't, am I submitting arbitrary data? The RFC5023, contains the description of the data structure of various resources for an Atom feed. An Atom client can use RFC5023 to interact with a compliant Atom feed. Similarly, I need to provide a document that describes the structure of various resources involved in my services. The document that I need is similar to the document provided by the Twitter data API OR the YouTube data API.

KandadaBoggu 2010-04-16 16:03:03

See the AtomPub <accept> element for how a server can tell a client what the client can POST. There is difference between providing a service description at design time (what is usually implied by 'API description') and the service supplying such information at run time. For example, you do not up-fron know where to POST your Amazon order, the service tells you right when you step through the purchase application. That way Amazon can change these implementation details at any time.

Jan Algermissen 2010-04-16 18:51:38

Have not looked at YouTube API, but Twitter API is not RESTful but 'HTTP Type-I' (See http://www.google.de/search?q=classification+of+HTTP+APIs first hit and use cached version because my server is currently gone)

Jan Algermissen 2010-04-16 18:52:16

ansaurus

tags:

views:

answers:

Self documenting REST interface

related questions