Below is a list of links I have found and some thoughts about each of them.
- WADL (Web Application Description Language) reference: apigee uses WADL to generate a console to your API but it requires that you describe your API in WADL.
- Do WADL's serve any purpose?: Not just WADL, but does any API specification serve to any propose and which proposes?
- Swagger: Another way/language to describe your API and then you can generate a console for your API and clients in some languages (the python code that it generates is terrible)
- Guide to specify API in Swagger: It seems to be easier to write than WADL and I prefer to write JSON than a XML file.
In my current job I'm writing an micro-framework called Tapioca for help people to create API's using Tornado. I have decided to create this project because I didn't found anything similar to use with Tornado. In Django you can use Tastypie or Django-rest Framework. Tornado projects can be made in so far different ways than in Django because in Django you normally follow an common sense to create projects and the framework is used in all levels of the application, since the database access until the web interface. Using Tornado you are completely free to use anything to database access and you not tells the framework which are and how are your models.
The objective of Tapioca is to provide a common behaviour to manage resources as close as possible to the definition of your RESTful API. I'm trying to follow the best practices of creation of RESTful API's. Other objective is to provide a automatic API specification in WADL and Swagger - so, then you will be able to use the apigee console or generate your own console using Swagger-ui.
I am working right now to figure out a way to generate those metadata to generate the specifications about an API created using Tapioca. I will post soon about it and while I am woking you can track what I am doing in the project github.
I'm not a native english speaker so if you found anything that I wrote is incorrect. Please, tell me and I will correct it.