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.
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.
A better overview is available here. It is possible in the future, with the gemification of our federation protocol, that we might be able to explore alternative federation API protocols such as Friendica Red and Tent.
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:
- Identity (for Authentication)
- ACL (app access permissions)
- 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?
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.
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?
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.