Request for comments: API specification draft

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/tags and GET /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