We’ve reached a point in the API bounty that it seriously needs a clear set of deliverables written down which should define;
The exact items that need to be implemented
How the bounty will be split when many developers submit parts of the needed items
So, any suggestions? I’d say let’s keep it quite specific and not try to cover a full set - something along the lines of the mobile version functionality + some of the missing core stuff there. I’ll throw a few things out:
Authentication, Authorization, and Format (60% of bounty):
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!)
Capabilities of the API (40% of bounty):
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
Optional, not required for the bounty, but worth noting in spec:
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
Opinions, comments? I’d like to write out a page in the wiki regarding this once we agree on a set of minimum accepted deliverables to cash in the $1000. I think for that we can demand at least basic functionality… But I’d personally like to keep the unnecessary complexity out in the first version. Features first, more ACL and fancy stuff later…
Note: This discussion was imported from Loomio. Click here to view the original discussion.
My main concern with this list is that we are asking for so much stuff that no one will even make a start on it.
It’s a comprehensive list for sure, and it’d be amazing to get all that, but considering the project is four or five years old now and we still don’t have an API I’m worried a list this size will scare some people off.
With the auth/core sorted, it’d be much easier to expand and build in the extra features.
So, my random thoughts/questions:
Do we need the ability to manage aspects from day one? We still can’t even do this in Mobile, never mind via API
I’m not sure managing tags is needed this early on either. Sure, it’s a nice to have, but we can live without it for now.
In terms of splitting the reward, that’s a good question.
Lets say three people work on this. If Person A spends 20% of their time, Person B spends 30% and Person C spends 50%, would we just split the bounty the same way?
The hard part would be deciding/agreeing on which person spent the most amount of development time on it I guess. Needs more thought for sure. Do bountysource have any guidelines or suggestions on this area? They must encounter this all the time.
Is making the web application compatible with this API a requirement?
If so should the API’s URLs be completely decoupled from the web app? Here is what I imagine. Let us say you want to view a single post with ID #1 once the API is implemented. The user will go to https://www.example.com/posts/1. The controller will send a request to https://www.example.com/api/v1/posts/1 with the user’s access tokens (assuming the authorization process has already been taken care of). The API will return a JSON response, which the controller will then send back to the browser. Is this what we are aiming for? If so what do we plan to do with the mobile site which doesn’t handle JSON?
“I’m worried a list this size will scare some people off.” Maybe the way this list is presented is a bit deceiving. I don’t actually have any experience building APIs but I assume the authentication and then authorization process of OpenID Connect is the bulk of the work. Maybe presenting it like the following will make it less scary?
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!)
Capabilities of the API
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
Also what does it mean by “API must define resources”? I interpret that as the API must use the resources that have already been implemented. If so, is that bullet point necessary?
As I mentioned before, I don’t have any experience but if someone is going to take the lead on this, I would be interested in helping out with this API development.
Is this what we are aiming for? If so what do we plan to do with the mobile site which doesn’t handle JSON?
No, no one has afaict mentioned that kind of plans.
Maybe presenting it like the following will make it less scary?
Great idea, thanks, will edit the list in the first post.
Also what does it mean by “API must define resources”?
It means the API should allow querying what resources it has available. It’s not really strictly necessary, but allows clients to optionally check for example what API version is available and whether a particular resource is available. I guess we could leave this point out to shorten the list, but I’d assume it’s not a huge thing to push out since we really want a versioned API anyway. I’ll push it to the optional section.
Then there is the splitting of the bounty. David from Bountysource replied to me (sorry been busy with work so this has been pending on me…) and he gave two options:
manually split the bounty between multiple developers, so long as a) the issue is closed and backers are happy b) all developers involved publicly agree to the split details (eg $100 to X, $250 to Y, etc)
If you create multiple, smaller tasks that collectively accomplish the “API Needed” goal, I could help you move bounties off this issue and onto those.
I’d say 1) is easier and more flexible, 2) will be more work.
I personally have never done a REST API with Rails, so I’m a bit hesitant to start putting percentages. I’d maybe start with the two main categories, split those, maybe even 50% if no one has better guesses, and then split down if needed in the wiki spec.
@jhass@dennisschubert@steffenvanbergerem do you guys (with more Rails experience) have some ideas on the weight we could give to particular areas suggested here in the deliverables? 50/50 between the main groups ok?
I’d actually go 60/40 for authentication & base infrastructure, which is more important to get right. The second point is “just” designing the routes, scopes and implementing them, which we can later more easily iterate upon by introducing new API versions.
It still needs some more specific notes, but any comments for now? I’d like to get this “accepted” so it can be linked to the bounty and “advertised” over the social media channels to potential developers.
@jasonrobinson Just to echo what @goob said mate, props for all the time and effort you’ve put in to this one!
I’ve not done one in Rails but have coded plenty of APIs in .NET and I’d also agree with @jhass re the percentage splits, the auth mechanism is by far the majority of the work.
I’ve made a minor change to ‘Note2’ on the wiki, just to add in the requirement of Bountysource that the splits are accepted publicly.
Edit: Nevermind, it seems that Nov’s sample provider implementation implements all three. I now plan to support all three in a similar fashion.
Augier and I have started to implement this API. Currently I’m working on the part where bearer access tokens are exchanged for resources (e.g., user info, posts, etc). According to “RFC 6750 Bearer Token Usage 2. Authentication Requests,” there are three ways that the bearer access token can be exchanged for resources: via authorization header field, via form encoded body parameter, and via URI query parameter. Nov’s sample provider implementation supports via authorization header field and via URI query parameter. According to RFC 6750, via authorization header field is a must while the other two are optional. In fact, RFC 6750 recommends that the optional two should not be used unless via authorization header field is impossible. I’ve already gone ahead to implement and test via URI query parameter and I plan to add tests for via authorization header field. I don’t personally plan to support via form encoded body parameter. Does that sound ok?
No more notes to the wiki page recently, so I’m publishing it to the issue, social media and bountysource. We can fill in more details as time goes on.
As suggested by cmrd-senya@github in the API development issue thread on github.com, I would like to raise the question whether it’s possible to share the bounty. For this question to be answered, frankrousseau@github would need to chime in to approve or disapprove this possibility, since he’s been working on this issue lately and afaik done the lion share of the work so far.
Any other opinions on bounty sharing and the API issue in general are greatly apprecieated.
I am hoping to put a lot of effort into the API in the very near future (like today and the next few weeks), building off the work Frank did. I didn’t notice there was a bounty on it when I decided to do that. If it is a splitting it thing and some of that would hypothetically go to me I will either donate that to another bounty or ask that my share be redirected towards some other financial support thing on the Diaspora project (hosting, another bounty, etc.). I’ve never done anything with the bounty system and I’m sure I’m being presumptuous about whether I’d see any of it because I haven’t done even one line of code towards the API. However I wanted to state that out of the gate since my aspirations are to put some heavy development heft behind getting this done.
Just a quick update. Frank and I are wrapping up the last of the internal PRs from the final code scrub and the grafting in of the new scopes stuff that @comradesenya worked on. This will ready for the real code review and PR process in the next week or so.