User:DenSchub/Diaspora API proposal: Difference between revisions

Latest revision as of 02:09, 23 March 2017

Warning:

This page is outdated at this moment. Please check the API docs draft for more information.

If you're a developer interested in working with Diaspora's API, please give feedback on the APIs detailed below.

Authentication model

The hard part is to provide a proper authentication layer suitable for all sorts of clients, be it other webservices, desktop clients, home servers or mobile devices. Getting a proper authentication model is the one important step, once that's done everything else is mostly defining the routes and JSON structures and some boilerplate code to implement them. For this, we have chosen OpenID Connect as a solution to the problem.

What is OpenID Connect?

From the OpenID Connect intro:

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner. OpenID Connect allows clients of all types, including Web-based, mobile, and JavaScript clients, to request and receive information about authenticated sessions and end-users. The specification suite is extensible, allowing participants to use optional features such as encryption of identity data, discovery of OpenID Providers, and session management, when it makes sense for them.

How does it work?

A simple flow is shown below:

+--------+                                   +--------+
|        |                                   |        |
|        |---------(1) AuthN Request-------->|        |
|        |                                   |        |
|        |  +--------+                       |        |
|        |  |        |                       |        |
|        |  |  End-  |<--(2) AuthN & AuthZ-->|        |
|        |  |  User  |                       |        |
|   RP   |  |        |                       |   OP   |
|        |  +--------+                       |        |
|        |                                   |        |
|        |<--------(3) AuthN Response--------|        |
|        |                                   |        |
|        |---------(4) UserInfo Request----->|        |
|        |                                   |        |
|        |<--------(5) UserInfo Response-----|        |
|        |                                   |        |
+--------+                                   +--------+

In diaspora*, this would mean that each pod becomes an OpenID Provider (OP). Any client should, ideally, allow specifying what OpenID Provider (diaspora* pod) the user would like to authorize with.

Adding an OpenID Provider to diaspora*

The official Ruby library is here.

Client API

We need to establish an official client API for diaspora* apps. Many users would love to have native mobile clients, for example.

Funding the API via Bountysource

Currently, $1000 has been donated to build a client API for diaspora*. This led to the need to lock down deliverables required to earn this (or parts of this) sum. The discussion is on Discourse. The deliverables are split into two major groups, and will be, if necessary split down further. Any person who implements a part of a group will be eligible for their share when the bounty is paid out by Bountysource.

Group 1 - Authentication, Authorization, and Format

This will count for 60% of the bounty money and contains the following deliverables:

API must be versioned
API must be RESTful (http://en.wikipedia.org/wiki/Representational_state_transfer)
API uses JSON for representing
Client must be able to authorize user using OpenID Connect (http://openid.net/connect/)
User must be able to view authorized apps from the web UI
User must be able to disconnect the authorized app from the web UI
Client must be able to request read and read/write permissions separately (let’s keep it simple and expand later if needed!)

Group 2 - Capabilities of the API

This will count for 40% of the bounty money and contains the following deliverables:

Post status messages and upload photos
Post comments
Read the stream(s) and a single post
Like, reshare and manage delete posts/comments
Read and write conversations
Search for users and tags
View a profile and retrieve user photos
Retrieve generic pod information (name, version, etc - statistics page basically)
View and manage notifications

Developing for the API

Any developers interested should indicate their interest in the relevant GitHub issue. Once you are sure how to continue, feel free to work on items interesting to you. Be sure to submit a PR as early as possible instead of polishing it too far.

Once you have submitted code towards the API, make sure to add your name to the claims in the Bountysource API page with an indication on what parts you have submitted.

Note! Any claims will be paid out once the whole issue is closed, NOT once individual PR's are merged in implementing parts of the above items.

Note2! Bountysource will split the money to individual developers based on 1) project team assessment of who deserves what, 2) publicly accepting your agreement of the above percentage splits in advance and 3) acceptance of the pay out from the people who donated to the bounty. Complaints against either of these are null.

Note:

Please contact the developers with any questions regarding developing for the API. Don't try to guess things through if you are unsure how the core developers would prefer things to be implemented - you will only be disappointed later in code review.

Development status

Work on the access token and authorization parts started by Augier and Kent Shikama (4th July '15)

Optional resources not required for the bounty, but part of the API spec

In the end, we want the API to be able to handle any actions that the website can handle. However, we are ok with the initial implementation not to contain everything, and as such these are option resources not part of the bounty.

Client must be able to manage followed tags
Client must be able to manage user ignores
Client must be able to manage aspects (create, delete, maintain users)
Client must be able to post a poll
API must define resources

@@ Line 1: / Line 1: @@
-{{Speculative}}
+{{Serious|This page is outdated at this moment. Please check [https://diaspora.github.io/api-documentation/index.html the API docs draft] for more information.}}
-This is merely a work-in-progress document to put some ideas together about a set of APIs for Diaspora and how they would work. Keep in mind, this article at this point is a stub. It will be polished up several times over before a vote is put forward.
 If you're a developer interested in working with Diaspora's API, please give feedback on the APIs detailed below.
@@ Line 50: / Line 48: @@
 The official Ruby library [https://github.com/nov/openid_connect is here].
-=== Third Party Client API ===
+=== Client API ===
-We need to establish an official client API for Diaspora apps. Many users would love to have native mobile clients, for example. A comprehensive list of functionalities will need to be addressed:
+We need to establish an official client API for diaspora* apps. Many users would love to have native mobile clients, for example.
+==== Funding the API via Bountysource ====
+Currently, $1000 [https://www.bountysource.com/issues/295-api-needed has been donated] to build a client API for diaspora*. This led to the need to lock down deliverables required to earn this (or parts of this) sum. The discussion [https://discourse.diasporafoundation.org/t/the-api-bounty-deliverables/502 is on Discourse]. The deliverables are split into two major groups, and will be, if necessary split down further. Any person who implements a part of a group will be eligible for their share when the bounty is paid out by Bountysource.
+===== Group 1 - Authentication, Authorization, and Format =====
+This will count for 60% of the bounty money and contains the following deliverables:
+* API must be versioned
+* API must be RESTful (http://en.wikipedia.org/wiki/Representational_state_transfer)
+* API uses JSON for representing
+* Client must be able to authorize user using OpenID Connect (http://openid.net/connect/)
+* User must be able to view authorized apps from the web UI
+* User must be able to disconnect the authorized app from the web UI
+* Client must be able to request read and read/write permissions separately (let’s keep it simple and expand later if needed!)
+===== Group 2 - Capabilities of the API =====
+This will count for 40% of the bounty money and contains the following deliverables:
+* Post status messages and upload photos
+* Post comments
+* Read the stream(s) and a single post
+* Like, reshare and manage delete posts/comments
+* Read and write conversations
+* Search for users and tags
+* View a profile and retrieve user photos
+* Retrieve generic pod information (name, version, etc - statistics page basically)
+* View and manage notifications
+==== Developing for the API ====
+Any developers interested should indicate their interest in the relevant [https://github.com/diaspora/diaspora/issues/3467 GitHub issue]. Once you are sure how to continue, feel free to work on items interesting to you. Be sure to submit a PR '''as early as possible''' instead of polishing it too far.
+Once you have submitted code towards the API, make sure to add your name to the claims in the [https://www.bountysource.com/issues/295-api-needed Bountysource API page] with an indication on what parts you have submitted.
+'''Note!''' Any claims will be paid out once the whole issue is closed, NOT once individual PR's are merged in implementing parts of the above items.
+'''Note2!''' Bountysource will split the money to individual developers based on 1) project team assessment of who deserves what, 2) publicly accepting your agreement of the above percentage splits in advance and 3) acceptance of the pay out from the people who donated to the bounty. Complaints against either of these are null.
+{{Note|Please [[How_we_communicate|contact the developers]] with any questions regarding developing for the API. Don't try to guess things through if you are unsure how the core developers would prefer things to be implemented - you will only be disappointed later in code review.}}
-* Streams
+===== Development status =====
-* Posts
-* Re-Shares
-* Likes
-* Comments
-* Aspects
-* Identity (for Authentication)
-* ACL (app access permissions)
-* Messages
-* Photos
-* Profiles
-* Tags
-* Cross-posting
-* Ignoring
-* Location
-* Application Name
-Another interesting question worth asking would be whether or not to share content from a webapp onto Diaspora itself, and how to do it. If a user shares a video from a MediaGoblin installation with some kind of Diaspora cross-posting button, should any link to the content be hiddden, should oEmbed content be rendered in posts and on the stream? At what level can apps be leveraged as part of a good user experience?
+* Work on the access token and authorization parts [https://discourse.diasporafoundation.org/t/the-api-bounty-deliverables/502/10 started] by Augier and Kent Shikama (4th July '15)
-=== Migration API ===
+==== Optional resources not required for the bounty, but part of the API spec ====
-This is an API not specifically made for clients; but rather, for transfer of user data. A Migration request would work like so:
-# User registers on the target pod that they want to transfer to.
-# User makes two-way OAuth connection between accounts on both pods.
-# User clicks "Export" on old pod in User Settings panel, data is transfered securely to their account on the target pod.
-# All likes, messages, status updates, photos, and contacts are moved over
-# As a final act, the original account closes down, all federated content from user is now attributed to new account on different pod.
-=== TOS;DR API ===
+In the end, we want the API to be able to handle any actions that the website can handle. However, we are ok with the initial implementation not to contain everything, and as such these are option resources not part of the bounty.
-[http://tosdr.org/ Terms of Service, Didn't Read] is an initiative to provide accurate reporting of the Terms of Service from many different web applications. One common complaint about Diaspora is that not all pods have readily-available Privacy Policies or Terms of Service. What's worse, many podmins end up having to hack in extra pages to make such things readily available to end users.
-With TOS;DR, a podmin could easily edit a tos.yml file with calls for different labels, and they would be displayed graphically on a user registration form, and Pod Uptime could be able to pick up the different service terms varying from pod to pod. Any time the tos.yml gets updated, users could be provided a form to approve the new usage terms, or be guided to export their profile and user data to a pod more suited to their needs.
+* Client must be able to manage followed tags
+* Client must be able to manage user ignores
+* Client must be able to manage aspects (create, delete, maintain users)
+* Client must be able to post a poll
+* API must define resources
+[[Category:Proposals]]