Auto documenting REST API in PHP

Question

phpDocumentor seems to be the standard for documenting PHP code, though I have to wonder why it hasn\'t been updated in years..?

However, it does not seem suitable f

Answer 1

A RESTful API should be entirely discoverable and auto-documented. You only need an URL and everything else linked to it should describe itself. Sounds like an utopia, but it's feasible.

For example, let's start out with a stackoverflow-like sample URL: http://restfuloverflow.com (illustrative)

The first thing you do on a RESTful resource is an OPTIONS request. You always need to include an Accept header to instruct the server to respond to the most appropriate mime type:

OPTIONS * HTTP/1.1
Accept: text/html, text/xml, application/json
Host: restfuloverflow.com

The server should instruct the client on what is possible to do on that URL:

HTTP/1.1 200 Ok
Allow: GET, POST, PUT, DELETE, OPTIONS, TRACE, PATCH

This is the RESTful API telling you that this service support these methods. The first one you'll try is something like the request below. An user hitting the API with a browser should work in a similar way.

GET / HTTP/1.1
Accept: text/html, text/xml, application/json
Host: restfuloverflow.com

The server then should return some links pointing to related resources, if available:

HTTP/1.1 200 Ok
Content-Type: text/xml



    
    
    

An HTML version should use links, and JSON responses should use JSON-Schema links attribute.

Let's say the client now decides that it wants to know what to do with questions:

OPTIONS /questions HTTP/1.1
Host: restfuloverflow.com
Accept: text/html, text/xml, application/json

A possible response could be:

HTTP/1.1 200 Ok
Allow: GET, POST
Content-Type: text/xml



    

Well, the server told us that it's possible to GET and POST a new question. It also told us how a question in XML looks like by providing a XML Schema. A JSON-SCHEMA could be provided for JSON, and in HTML a form for new questions could be provided.

Let's say the user wants to GET questions:

GET /questions HTTP/1.1
Host: restfuloverflow.com
Accept: text/html, text/xml, application/json

Then the server responds:

HTTP/1.1 200 Ok
Content-Type: text/xml



    
    

Now, everything is linked again. The thing keeps going in a way that the service describes itself. The Netflix API follows similar principles, but lacks some auto-discover features.

This Brazillian Government API describes itself using RDF. It's one of the best RESTful samples I've ever seen. Try changing .rdf to .xml, .json or .html. (It's all in Portuguese, sorry for that).

The best tool for RESTful APIs in PHP is Respect\Rest. It has most of the workflow I've described here already bootstrapped, and new features are coming (It's still in 0.4x version).

The cost of building a documenting system for RESTful applications is the same as building a RESTful application. This is why there are so few tools like that, and usually they're not that good.