Sat 20 Feb 2016 11:30AM

Request for comments: API specification draft

DS Dennis Schubert Public Seen by 97

So, since we now have a nice API authentication implemented I think we should ship with an API if we manage to implement it in time. Initial work was already done in #6636 but after taking a look with it, I felt like we really should think about a proper structure for our API, especially since our backend models are rather... complex and simply exposing anything to our API does not feel like the right thing to do.

The initial work by @theworldbright was based on jsonapi, but after a small chat over IRC, we both agreed that following jsonapi creates a lot of unnecessary overhead. So I went ahead and wrote an API proposal (actually, I wrote a whole documentation so we would be ready to go...) and I'd like to have some feedback. Most of the routes are simple RESTy JSON routes. Pagination is done via Link headers which also is a somewhat "usual" approach that I have seen in various places, for example in GitHubs API.

There we go: https://diaspora.github.io/api-documentation/

Feel free to ask any questions and make suggestions. If you find a spelling or grammar error, please submit a PR and keep that out of Loomio since that would create a lot of noise. ;) If no one has objections, I'd move the repository over to the org rather sooner than later and add links to the wiki, so everyone interested in API work has an easy time finding that documentation.


Steffen van Bergerem Sat 20 Feb 2016 11:52AM

I already did a few reviews in the last couple of days and did a final review a few minutes ago. The proposal looks good to me.


Armando Lüscher Sat 20 Feb 2016 4:09PM

For the Notifications:
All notification types are set to past tense except for "comment_on_post".
I'd suggest and encourage to change this to "commented_on_post" to follow the same structure.

Other than that I've made a few PRs and am seriously looking forward to the API becoming reality!
Awesome work, thanks!


Creak Sat 20 Feb 2016 6:17PM

That seems pretty awesome.

I don't know much about the architecture of D*, but if there is no such API as of today, does it mean that D* makes direct calls to the backend to fetch the data to display?


Creak Sat 20 Feb 2016 6:34PM

I'm not a lot familiar with REST APIs, so the next question might be stupid.

What is the meaning of ":" in the URL?
For instance, to get the information about an aspect, it's written like that:

GET /api/v1/aspects/:aspect_id

But why not using "?" as a separator between the request and the arguments? Like something like that:

GET /api/v1/aspects/?id=aspect_id

That allows to use GET method for most, if not all, of the requests.


Steffen van Bergerem Sat 20 Feb 2016 6:39PM

If the aspect id is 4 then the route would be

GET /api/v1/aspects/4

This is important for routes like the one to receive comments of a post. If the post guid is 23 then you can get the comments with

GET /api/v1/posts/23/comments

The colons just tell you that this is a parameter that needs to be set to the correct value.


Creak Sat 20 Feb 2016 6:47PM

Oh ok!

I thought it meant that we should do that:

GET /api/v1/aspects/:4

So that brings me to my next point: would be nice to add one or two examples after the Request and Response sections ;)


Steffen van Bergerem Sat 20 Feb 2016 6:55PM

would be nice to add one or two examples after the Request and Response sections

I think those who read the specs because they would like to write software that uses the API will be able to understand the current state of the specs. Especially because they will have to work on the OpenID connect authentication first.


Manuel Vögele Sun 21 Feb 2016 8:40PM

Seems like the the feature to reorder aspects is missing. But aside from that it looks good to me.


Dennis Schubert Mon 22 Feb 2016 10:50AM

@manuevogele yeah, why not. I added the aspect order id. Thanks!


Kitsune Thu 25 Feb 2016 12:25AM

I've skimmed over the spec. For me as a layman, it makes a very good and clean impression. One central question: what about error handling? Will there be a combination of HTTP error code and a standard JSON object with qualified error information? (I asked myself what happens, when the client is trying to create a new conversation and the client GUID is missing in the recipients list? A HTTP status code like 403 seems to be too little in this case.)

Load More