User:DenSchub/Diaspora API proposal

Speculative:

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.

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.

Read more about a basic usage example.

Adding an OpenID Provider to diaspora*

The official Ruby library is here.

Third Party 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:

• Streams
• 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?

Migration API

This is an API not specifically made for clients; but rather, for transfer of user data. A Migration request would work like so:

1. User registers on the target pod that they want to transfer to.
2. User makes two-way OAuth connection between accounts on both pods.
3. User clicks "Export" on old pod in User Settings panel, data is transfered securely to their account on the target pod.
4. All likes, messages, status updates, photos, and contacts are moved over
5. As a final act, the original account closes down, all federated content from user is now attributed to new account on different pod.

PodStatus API

Create an API dedicated specifically for reporting the following variables:

• Is the pod up and running?
• Is it federating with the network?
• What version is it running?
• How many publicly registered active users are on the pod?
• Is the pod open for registrations?

TOS;DR API

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.