Some API requirements

[Floppy]

We'd like to try out Loomio with the OpenPolitics project. We currently discuss votes in pull requests, but Loomio might do a better job. So, in order to do this we would need API access to Loomio to do a few tasks. We currently have a script that monitors vote status, so we'd be integrating into that.

Note that I'm not massively familiar with Loomio yet, so apologies if some of this doesn't make sense.

First, we need to create a Loomio discussion automatically when a pull request is opened, and enter the link to the discussion as a PR comment. API features required:

• create discussion and set description (including links)
• get link to created discussion

Next, we'd need to monitor the status of the discussion and set github merge status appropriately. API features:

• get number of votes for/against/abstain for a discussion, and whether a vote has been passed.

Finally, when contributions are accepted, we'd need to invite the new contributors to Loomio and add them to later iscussions automatically. API features:

• create Loomio invitations for new users

Hopefully this helps show what we want to do... looking forward to having a go :)

[rdbartlett]

Thanks for this @Floppy! @robguthrie does this kind of detail give you a better idea?

[mikeumus]

As requested @rdbartlett, right now some high-level app ideas we have are:

• a Chrome extension that gives Loomio notifications and lets you comment/vote.
• a Chrome extension that integrates with GitHub for embedding decission making inline.
• a Google Glass app(and wearable SDK, checkout WearScript) for Loomio decisions on the go.

---

This would involve needing some the API the ability to:

• authenticate as a user in context to the Loomio group.
• post a:
  • vote
  • comment
• get a:
  • comment(s)
  • vote(s)
  • pie chart(s)

[edwardgalligan]

As a very quick counter to @mikeumus's comment, I see quite a lot of modern web service API set up with a user context in mind - aimed at user applications (particularly mobile). These are often OAuth based.

While this is a really common + valid use-case, often these APIs lack additional methods of querying without a user context, which I think is also an important (perhaps equally important) use-case.

For example, if I want to pull API data related to a Loomio group over to integrate it into that groups main website, either to promote engagement or to provide an additional endpoint for getting info on decisions made.

So I think having some (read-only) API access without requiring a user context is important. This could be purely for retrieving publicly-accessible data, or perhaps API keys could be associated with Loomio groups if there were use-cases for retrieving private discussions.

[mikeumus]

@lucideer make a excellent point here. There are to contexts/uses of an API. One when a user needs to auth to vote remotely via the Loomio API and another when a "Org" app is simply requesting read-only data as @lucideer said, into an app. And for the Org context having a developer register their app at developers.loomio.org to get their API Credentials, (Key & secret), is the way to do that. 👍

[Floppy]

Yes, we'd definitely need org-level access to do things in a non-user-centric way. OAuth bearer tokens are the usual way, I think.

[Floppy]

I might have some time this week to spend on this, if I can help - is there some API work that I can help out with, or is it still too early stage?

[rdbartlett]

Thanks @Floppy! I know @robguthrie has started on a commenting API as part of the work we're doing on emails at the moment. Rob can you share any updates?

[robguthrie]

We're going to have a write only api around comments to be used by the
email gateway, and a full access api for clients that can maintain a
session.

I'm working on the groundwork now. Expect some news in 1 week.

On Tue, Jun 24, 2014 at 9:59 AM, Richard D. Bartlett <
notifications@github.com> wrote:

Thanks @Floppy https://github.com/Floppy! I know @robguthrie
https://github.com/robguthrie has started on a commenting API as part
of the work we're doing on emails at the moment. Rob can you share any
updates?

—
Reply to this email directly or view it on GitHub
#1530 (comment).

[almereyda]

An API could also include Webmention functionality, so federated conversations appear closer.

@elf-pavlik

[elimisteve]

@rdbartlett @robguthrie What is the current architecture of Loomio, especially the latest, Angular-using one? Is there an API that Angular uses?

If there isn't already, are there plans to do some dogfooding of sorts, where the default Loomio UI's JS is using, say, an X-Auth-Token header in the AJAX calls it does to GET/POST/etc content? Obviously that would make it easier to "create" an API for other purposes; the same one could be used :-).

So far it seems like the question has been some version of, "what functionality should be exposed via the API?", but if Loomio is architected as mentioned (or similarly), I think that question becomes unnecessary.

[robguthrie]

The angular client works entirely off the API, which exposes pretty much all functionality. It's already at a point where anyone could build their own Loomio client. Authentication is still cookie based ATM.

I'm interested to hear requirements for server to server or "app" integrations on behalf of groups. IE: what is the agent that is not a user? What would it mean to grant an app access to your group?

[Floppy]

Basically, from my point of view, we want to manage the discussions automatically, based on submissions to a github repository. We're pretty much looking to replace PR-based discussion with Loomio, if we can. The main requirements are listed up top, so I won't reiterate, but we have a definite use for a non-human client.

[robguthrie]

Arrr.. sorry just caught up on that. The scenario you specify in the top post is entirely possible via the current v1 api, assuming you don't mind having a robot user as the author of discussions and you can manage auth via cookie rather than query token.

[Floppy]

No, that would be absolutely fine. Is there some documentation I should look at to have a go?

[robguthrie]

Just the specs and the code itself. I'll find some good examples for you:

https://github.com/loomio/loomio/blob/master/app/controllers/api/restful_controller.rb

All the api controllers inherit from this controller. It provides create, update, destroy methods. The next update (due in a few days) will support both keys and ids as identifiers for records.

If you request something like https://www.loomio.org/api/v1/discussions/kqSCLEPd then you'll see a typical response in the format of:

{ users: [...], proposals: [...], discussions: [..] }

Records reference each other by id or key ie: we don't embed them in associations.

It seems you'll need to be logged in to see that response.. you shouldn't need to be but we've been totally focused on our own needs right now.. and our client is currently only available to logged in users. We'd be happy to consider a pull request that fixes permissions for public content :)

[yourcelf]

I'm interested in developing other types of group interactions beyond the discussions and voting that loomio provides (https://intertwinkles.org for example). The number 1 challenge I've encountered with this is the friction of authenticating, setting up and defining groups, inviting members, etc. It's hard to convince non-technically inclined member of your group to set up yet another user account on yet another service. So basically, I want to let users "sign in with loomio", and for them to be able to bring with them the whole group model along with it. Other developers should never have to rewrite the basic group model / authentication stuff again.

So for my use case, an OAuth based approach works fine, as long as the API allows access to the groups and membership related to that user. So if that user creates a new activity/document/whatever, and another member from ther group comes along, the other member can get automatic access to it. I think this could really reduce the barrier to developing new group interactions.

Next levels for this would be to:

• Allow external apps to post "cards" or updates in a loomio activity stream, including email notifications, so work done in external apps can sit alongside discussions and proposals.
• Allow external apps to post search text that shows up in loomio's search.

I think the API approach for this is likely to be more successful than a "plugin" approach -- that way, loomio.org doesn't have to be responsible for compatibility with integrations. Loomio has the opportunity to become the central group-ware hub, handling all the nitty gritty of user accounts and access, without becoming another difficult-to-maintain monolith like redmine etc.

[robguthrie]

That sounds super exciting. This kind of thing is very similar indeed to
the the requirements we have of our "plugin" system. We'd like to clearly
define a way to add support for other decision types to loomio, ideally
moving proposals over to this generalised framework.

I think the OAuth stuff is a lot less work than the second part enabling to
be defined services to insert content into discussion threads and
notifications, and agree that lots of other systems could benefit from
users being able to connect/adopt an existing loomio group. Sounds like a
good place to start.

Maybe we should have a skype call about this next week?

On Fri, Dec 12, 2014 at 1:56 PM, Charlie DeTar notifications@github.com
wrote:

I'm interested in developing other types of group interactions beyond the
discussions and voting that loomio provides (https://intertwinkles.org
for example). The number 1 challenge I've encountered with this is the
friction of authenticating, setting up and defining groups, inviting
members, etc. It's hard to convince non-technically inclined member of your
group to set up yet another user account on yet another service. So
basically, I want to let users "sign in with loomio", and for them to be
able to bring with them the whole group model along with it. Other
developers should never have to rewrite the basic group model /
authentication stuff again.

So for my use case, an OAuth based approach works fine, as long as the API
allows access to the groups and membership related to that user. So if that
user creates a new activity/document/whatever, and another member from ther
group comes along, the other member can get automatic access to it. I think
this could really reduce the barrier to developing new group interactions.

Next levels for this would be to:

• Allow external apps to post "cards" or updates in a loomio activity
  stream, including email notifications, so work done in external apps can
  sit alongside discussions and proposals.
• Allow external apps to post search text that shows up in loomio's
  search.

I think the API approach for this is likely to be more successful than a
"plugin" approach -- that way, loomio.org doesn't have to be responsible
for compatibility with integrations. Loomio has the opportunity to become
the central group-ware hub, handling all the nitty gritty of user accounts
and access, without becoming another difficult-to-maintain monolith like
redmine etc.

—
Reply to this email directly or view it on GitHub
#1530 (comment).

[yourcelf]

@roboguthrie, I'd love to chat. I'll contact you privately for schedule coordination.

[denjello]

Is this an issue, or a discussion?

[Floppy]

I originally added it as a discussion of a few of our API requirements, but I think the API has moved on a lot since then.

[edwardgalligan]

the API has moved on a lot

Querying a few of the current live endpoints anonymously give me 401s so I'm guessing the current v1 is intended user-centric access only? Has any thought been given to non-user-context API access discussed last summer?

Would be really nice if, for example, when visiting the following endpoint anonymously:
https://www.loomio.org/api/v1/discussions?group_id=3
it returned a JSON serialisation of the content shown for logged out users visiting this page:
https://www.loomio.org/g/WmPCB3IR

[robguthrie]

we're still building on it. I completely agree with you on the intended behaviour @lucideer.
IE:
If you are not logged in and request discussions index, then you should see public discussions

[denjello]

+1 for transparency
+10 for federated data structures without middleware

On 02/03/2015 10:52 PM, Robert Guthrie wrote:

we're still building on it. I completely agree with you on the intended behaviour @lucideer.
IE:
If you are not logged in and request discussions index, then you should see public discussions

---

Reply to this email directly or view it on GitHub:
#1530 (comment)

[edwardgalligan]

we're still building on it. I completely agree with you on the intended behaviour @lucideer.
IE:
If you are not logged in and request discussions index, then you should see public discussions

Has there been any movement on this? Just checked the same endpoints quickly now:

• https://www.loomio.org/api/v1/discussions?group_id=3 still works for authorised requests so I assume there hasn't been huge structural/functional changes
• https://www.loomio.org/api/v1/discussions?group_id=3 now returns a 500 instead of a 401 for anon requests

(and https://github.com/loomio/loomio/blob/master/config/routes.rb shows no v2 yet, so I assume I'm still looking at the endpoint for the current version)

[gdpelican]

Hey @lucideer, there has been a bunch of movement on the API, but we've still been focusing primarily on internal usage at the moment (we've extracted the client and server facing parts of the API into gems, actually: www.github.com/gdpelican/snorlax; www.github.com/loomio/angular_record_store).

Once Loomio 1.0 is released later in the year, we'll be be able to better prioritise public-facing content. We do have one endpoint exposed, a list of recent public motions which conform to the popolo spec (http://www.popoloproject.com/specs/motion.html), check it out here:

https://www.loomio.org/api/popolo/motions.json

if there was an interested dev with a little experience out there I'd be more than happy to support her/him in getting some other endpoints exposed; it's really not a long ways off at all, but I can't guarantee it'll make it on our list before 1.0 is out in the wild. 🐯

[edwardgalligan]

if there was an interested dev with a little experience out there I'd be more than happy to support her/him in getting some other endpoints exposed

I'd love to, but I'm not a Ruby guy - I could probably figure it out without a lot of difficulty but I think maybe getting loomio running in a dev env to begin with might be my biggest hurdle

[gdpelican]

Have you had a peek through the dev environment startup instructions?
https://github.com/loomio/loomio/wiki/Setup-a-Loomio-development-environment

Those are instructions for Ubuntu, but I can't imagine differences for Debian would be too severe (and we'd be happy to hear about them in a PR to that doc!)

You won't even need to worry about setting up the angular frontend business if you're just intending to work on the API, and if you get stuck, let me know. If you don't get stuck, let me know that, and I'll send over some instructions for how to get those endpoints working for you. 🆗!

[gdpelican]

Going to close this as it's not a particular 'issue' for us to fix at this point. If anyone's interested in using the Loomio API, get in touch with me and we'll discuss further how to make that easy for you.