View source for User:DenSchub/Diaspora API proposal

{{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.}}

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 [http://openid.net/connect/ OpenID Connect intro]:

<blockquote>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.</blockquote>

==== How does it work? ====

A simple flow is shown below:

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

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.

Read more about [http://openid.net/specs/openid-connect-basic-1_0.html a basic usage example].

==== Adding an OpenID Provider to diaspora* ====

The official Ruby library [https://github.com/nov/openid_connect 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 [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.}}

===== Development status =====

* 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)

==== 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
[[Category:Proposals]]