Loomio
Thu 11 Jun 2015 8:59PM

The API bounty - deliverables

JR Jason Robinson Public Seen by 35

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

JR

Jason Robinson Sun 28 Jun 2015 7:07PM

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.

G

goob Sun 28 Jun 2015 8:07PM

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

DU

Rich Mon 29 Jun 2015 6:39PM

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

KS

Kent Shikama Sat 4 Jul 2015 3:28PM

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?

JR

Jason Robinson Tue 7 Jul 2015 3:33PM

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.