So, since we now have a nice API authentication implemented I think we should ship 0.6.0.0 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.
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.
Note: This discussion was imported from Loomio. Click here to view the original discussion.
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!
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?
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.
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.)
diaspora_id: I don’t like product specific / platform specific names in a functional oriented interface. I would prefer a more neutral alternative like “handle”, “federation_id”, or “identifier”. (As I understand, the diaspora_id is also used to address Friendica and Red Matrix users?)
Contacts
Add a user: GUID is transfered by resource URL. An alternative way could be a JSON object. This would be a more consequent resp. “stringent” (but maybe a “non-comfortable”) way in comparison of other POST methods in the spec. Example: POST /api/v1/aspects/:aspect_id/contacts/ { "guid": "0a992a10b9db0133e40e406c8f31e210" }
Posts
Advanced Post Contents: maybe, this should be separated in request and response views. For instance, the polls object contains “guid”, “participation_count”, and “already_participated”. This looks like a set of response attributes, but I assume that polls can also be used in requests for new posts?
Mentions: Is this for response objects only? If both ways: Why is it the job of the client to extract the mentions as separate user objects? (And how does the client get the needed user data?)
Streams
Get the main stream -> Response -> post_type: this looks like an enum value. Which values are possible and what is their meaning?
Users
Get information about a single user -> „block“: Alternative name: “blocked” (“block” is - from my point of view - an imperative mood, but the attribute is not used in a command-like context?).
Update the currently authenticated users profile -> Request/Response -> birthday: Which format is expected? Why not ISO (YYYY-MM-DD), as it is used in the database?
Update the currently authenticated users profile -> Request -> name: I guess that’s the display name? But isn’t it neccessary to transmit first_name and last_name separated for the update process (according to the database structure)?
Update the currently authenticated users profile -> Response -> name: Is this the “combined” display name which is created via first_name + blank + last_name? (Should be mentioned in the explanation to clarify the interface’s behavior.)
Users vs. User
I don’t have a good feeling for the resources under /api/v1/user and /api/v1/users. First, I thought it’s a single resource because I didn’t notice the singular-plural distinction - it confused me for a while. For me, a user is a technical account on a specific pod which is used primarily for session handling (authentication, authorization, etc.). This account can be furthermore associated with a profile, which is the non-technical view on a person or principal. What I’m trying to say: the resource under /api/v1/users should be more a /api/v1/people or /api/v1/profiles (like the database structure, where “people” and “profiles” are used). BTW: in the mentions object (Posts section) “mentioned_people” is used instead of “mentioned_users”.
Oh btw. I don’t like that photos are called photos all over diaspora (in the database and the json-responses even in the UI). I’d say “images” would be the best term for these, because not every image uploaded is photo, half of the pictures I upload ain’t photos but “graphics” (or “graphs” ;D).
So I suggest to start in the api calling this stuff “image” or “images” instead of “photos”. Maybe it’s a bad idea to make this less continuous but I don’t like at all this kinda stuff is called photos.
Today I thought about a usecase one would need to access /public/ (all public posts on a pod). Maybe huge or weak pods would like to deactivate that. Or maybe podmins general want to restrict the frequence of requests.
And I couldn’t find any error-handling. Many errors might occur like no data for a request or invalid parameters or to many requests per time…
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.