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 
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.
Seems like the the feature to reorder aspects is missing. But aside from that it looks good to me.
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.)
Shame on me! Didn’t read the hint in the overview … But it’s quite interesting for me 
Looks verry well…
GET /api/v1/photos/:photo_guid
Isn’t there more information but dimensions and sizes? Maybe the datetime of upload? Or corresponding postings?
Posts → Publish a post → Poll
says “see above”. Is it really nessesary to tell points like participation_count, vote_count or already_participated?
What’s the difference of GET /api/v1/streams/tags and GET /api/v1/search/posts ?
I am missing “add user to aspect(s)” or “share with user” or the like.
In the end: Looks like a lot of work, hours and hours of writing, thanks for that.
General
- 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”.
diaspora_id: I don’t like product specific / platform specific names in a functional oriented interface.
Perhaps user-id?
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.
thx
How will diaspora api version be exposed with Nodeinfo? In the software section?
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…
This can be autogenerated like Propel ORM?
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.
Thanks, fixed.
Maybe the datetime of upload? Or corresponding postings?
Both added.
What’s the difference of
GET /api/v1/streams/tagsandGET /api/v1/search/posts?
One shows the tags you’re following, the other allows you to search for a tag…
I am missing “add user to aspect(s)” or “share with user” or the like.
https://diaspora.github.io/api-documentation/routes/contacts.html
diaspora_id: I don’t like product specific / platform specific names in a functional oriented interface.
This is the way we called the field internally. Names like ID are ambiguous, since that could be the numerical ID or the GUID as well.
Add a user: GUID is transfered by resource URL. An alternative way could be a JSON object.
I don’t really like that. First, your suggestion should be a PATCH, not a POST. That may work for adding. But how would you do deletions?
Advanced Post Contents: maybe, this should be separated in request and response views.
Maybe. I’d like to avoid duplicate content. Will add that if we run into confusions.
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?)
It’s response only, yes. I don’t understand your second question.
Get the main stream -> Response -> post_type: this looks like an enum value. Which values are possible and what is their meaning?
“The post_type field in a response could either be StatusMessage or Reshare.”
Get information about a single user -> „block“: Alternative name: “blocked”
Good point. Fixed.
Update the currently authenticated users profile -> Request/Response -> birthday: Which format is expected?
Added ISO 8601, thanks.
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
Well. Yeah. Fixed.
Users vs. User
Good points. Singular/plural routes are nothing unusual. I don’t want to split between people and profiles since users and developers should not care, but I’ll keep your points in mind if we ever run into trouble. Thanks!
And I couldn’t find any error-handling.
That’s the only ToDo point.
This can be autogenerated
Nah. Our database structure looks very different from what we expose. The database schema is way too complicated for an API.
Actually, I’ve reverted the first name and last name split. See https://github.com/diaspora/diaspora/issues/3648
It was requested I bring this up here specifically, For Client to Server, W3C has just come out with the Micropub spec https://www.w3.org/TR/micropub/.
There is already a test suite for it as well.
Any news on #API? 
I wanted to discuss the user archive export feature in the API. The possible use case is when I want to set up a remote application, like nextcloud to fetch and store my archive on a regular basis (say, once a day). We can add routes for that in a /api/v1/user namespace and we will probably need a separate access scope for this.
Any opinions?
1 Like
I don’t know if we want to support automatic exports, because it is really ineffective and would add a lot of load to pods. When people want a daily backup they should just create their own pod and create daily database dump. When we want to support some kind of continuous backup we probably should add a possibility to send every message to a backup pod (so you can import an older archive with the key, but all posts are already there), or add a possibility to create incremental archives which then can be combined at import (but that is both off-topic here).
We should maybe still add archive functions to the API, so you can download the archive from an app? But I would advise against using the API for daily backups (so not promote this as a use case), because when multiple users do this it would just kill the pod.