Loomio

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

DS

Dennis Schubert Thu 11 Jun 2015 9:04PM

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

DU

Rich Fri 12 Jun 2015 8:27AM

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

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.

JR

Jason Robinson Sun 14 Jun 2015 11:30AM

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

DU

Rich Sun 14 Jun 2015 9:24PM

Oh! They must come across it though, we can't be alone :)

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

KS

Kent Shikama Tue 23 Jun 2015 3:55AM

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.

DU

Rich Tue 23 Jun 2015 7:53AM

@theworldbright

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

No, it's not :)

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

AA

Alberto Aru Thu 25 Jun 2015 9:02PM

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

JR

Jason Robinson Sun 28 Jun 2015 8:59AM

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

JR

Jason Robinson Sun 28 Jun 2015 9:07AM

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?

JH

Jonne Haß Sun 28 Jun 2015 10:19AM

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.

Load More