User:DenSchub/Diaspora API proposal
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.
- 1 Authentication model
- 2 Client API
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:
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.
Read more about a basic usage example.
Adding an OpenID Provider to diaspora*
The official Ruby library is here.
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.
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.
- 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