We are migrating from an old forum solution (based on Teamforge) over to Discourse, and we have a few scripts and tools that we’d like to re-write to use the Discourse REST API. Being notoriously lazy, I’m wondering if there is a Swagger, WADL or simiar machine-readable description of the API that I can use to generate clients?
I’m not a particularly clever person, but from what I can see, that gem does not contain any information about what data is returned. Instead it relies on the API users somehow knowing what data is returned, which brings me back to my original problem of not having enough information to generate a strongly typed API.
Since my original post I’ve been playing around with Swagger a bit, and current-best-thinking is as follows:
Use the source code of Discourse (not discourse_api) to get an idea about which data types are used in responses, and what data they share.
Use discourse_api, the API documentation post and the Swagger specification created by @fantasticfears to get an idea about which requests exists, and what they do
Write a complete Swagger specification including output data that can be used to generate a client in all languages supported by http://editor.swagger.io/ (and share it, of course!)
I’m sort of confident I can write such a specification, but I have no idea if I should.
So: Does anyone know any reasons doing this would be a bad idea?
You are absolutely right. Though I think it’s a common problem for large RESTful website. It will takes so long time to just write the first draft of API These endpoints are so many and return different attributes based on user identity.
This is a fairly nice way because that’s how I understand these endpoints. Beside that, Network tab in browser tool will show how Ember.js client talks with Rails. You do some actions and you can watch how it goes.
Postman are also useful to try different endpoints by API. routes.rb is the central point of endpoints, you can find every endpoints there. The hardest part is that you can’t discover what parameters you have to send.
It will be so nice if we have this specification. But It takes HUGE amount of time. If you insist, focus on topic list, users, category, badges, posts, topics, topic actions endpoints.
This specification can be used to generate a Java API library (or any other supported language), which can then be invoked as below:
ApiClient client = new ApiClient();
DefaultApi api = new DefaultApi(client);
Site site = api.getSiteInformation();
String nameOfFirstGroup = site.getGroups().get(0).getName();
Categories categoriesResponse = api.getCategories();
String nameOfFirstCategory = categoriesResponse.getCategoryList().getCategories().get(0).getName();
As you see the generated API is strongly typed, and the name and structure closely reflects the REST API responses.
I aim to continue expanding it a bit, but I’m not sure I’ll ever get to a full implementation. Still, if this helps anyone other than me, that would be awesome. And if someone wants to help, even better! And even if I’m the only user, I’m still satisfied since I’ve gotten the opportunity to learn YAML, Swagger, JSON Schema and parts of the Discourse source code