An example of a well-established RESTful service

Question

I need to write RESTful service documentation. Does anyone know of very good written documentation for a RESTful service that I could use as a template for myself?

Thank.

Answer 1

Please refer to the REST API Documentives Best Practices documentation to document your RESTful service. The document covers all aspects. Here is a fragment of it.

Title: Show all users. URL: / users or / users /: id or / users? id =: id
Method: GET | POST | REMOVE | Put
URL parameter: Required: id = [integer] OR Optional: photo_id = [alphanumeric]
Data parameters: {u: {email: [string], name: [string], current_password: [alphanumeric] password: [alphanumeric], password_confirmation: [alphanumeric]}}
Answer codes: Success (200 OK), Invalid request (400), Unauthorized (401)

Answer 2

Have you heard of http://swagger.io/ ? It creates very useful (and nice) documentation for the REST API.

Give it a try. I really recommend it.

Answer 3

You can reference the Zoho Subscriptions API . This three-column document is resource-based and has a sample request and response for each endpoint.

Disclosure: I am part of the Zoho Subscribers Group.

Answer 4

The Twitter Api documentation is the best I've come across.

Answer 5

CouchDB API , "RESTful database.

You will notice that the document is structured by a resource rather than a method, which makes it more resource-oriented than most well-known API documents.

Answer 6

Try the rest-tool .

This is consistent with the linguistic agnostic approach to spec writing. Provides instant layout implementation and automatic unit testing for RESTful APIs off the shelf.

Services are specified through YAML files, and sample data can be placed next to descriptors. You can find the absont JSON schema in the service.yml descriptor file format. It can be used as a guild, but it can be expanded on demand.

Answer 7

The readability API has recently been featured on Twitter.

Disclosure: I am a partner in Arc90, creators of Readability and an investor in Readability.