The API bounty - deliverables

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):

  • 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!)

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.

2 Likes

Please elaborate the authentication, the API should use OpenID connect, not OAuth or something else from OpenID.

Excellent write up!

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 :slight_smile:

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.

@rich1 thanks! I updated the post, moving some of the non-critical things to the optional part.

I’ll ask bountysource about the splitting - their faq didn’t cover this question.

Oh! They must come across it though, we can’t be alone :slight_smile:

Yeah, it’d be good to know their thoughts.

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?

Authentication, Authorization, and Format

  • API must be versioned
  • API must be RESTful (http://en.wikipedia.org/wiki/Representational_state_transfer)
  • API must define resources
  • 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!)

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.

@theworldbright

Is making the web application compatible with this API a requirement?

No, it’s not :slight_smile:

I applauded Twitter in 2010 when they made that move but no, that’s not part of the scope or requirement of this particular Github/bountysource issue :slight_smile:

OpenID never worked to me (I tried a few of them, like the Wordpress OpenID)

@theworldbright

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:

  1. 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)

  2. 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.

Well I attacked the old wiki proposal for an API and tried to bring it up to date, highlighting the authentication and resources in brief.

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.

Thanks for all this work you’re doing, J. Sorry I can’t be of any help with it.

@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.

This is shaping up nicely :slight_smile:

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?

Awesome @theworldbright and @augier for working on that part!

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.

1 Like

Hey,

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’m lemonandroid@github.

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.

2 Likes

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.

1 Like

This is now out of internal review, ready for the real PR review, and is actively being used in a project I made for a discussion timeline on my blog…