User:DenSchub/Diaspora API proposal
This article is a work-in-progress.. .
This article is currently a speculative draft based on user feedback and developer needs. As such, it should not be interpreted as a canonical source of future information until the details are more further refined. improve the article by updating it. There may be additional information on the talk page.
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.
- 1 Authentication model
- 2 Client API
- 3 Migration 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 Loomio. 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 and 2) acceptance of the pay out from the people who donated to the bounty. Complaints against either of these are null.
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.