API Wrangling: Designing the API for Ushahidi v3.0

Ushahidi
Apr 12, 2013

[Cross post from Robbie Mackay's Blog] Following on from my Building 3.0 blog post, here’s another update on Ushahidi 3.0. We’re currently still pushing on finishing the 3.0 API, or at least the first cut at it. The original due date for this was March 30, but thats slipped to mid April. Conversations have quieted down a little as we get to work on getting things done. Thats good, but means we need to keep working hard to keep the community up to date on our progress.

API design primer

Designing an API seemed simple.. but once you get into the weeds and start building things there are a lot of questions to answer. I’ve done a chunk of reading as I tried to figure out:

What a proper RESTful approach would look like,

What’s normal practice, ie. where do developers often cut corners? why? is this good or bad?

A few valuable resources:

Web API Design from Apigee

Whitehouse API standards

Progress

The last couple of weeks have been dominated by the thousands of tiny decisions made at each step of building the API. I’ve tried to keep the wiki updated with the general patterns of our API. This gives a few guidelines

What methods to use, and how to accomodate more complex queries (ie. search)

What HTTP response codes to use

What to cover in functional tests

How to expose relations and links beteen resources

We’ve got the basics in now:-

Forms, with their attributes

Groups

Posts

This gives us enough to start experimenting, but there are still a lot of loose ends. The next things we’re looking at are:

Sets,

Tags

Users - along with their roles and permissions

Extensions to posts - adding revisions, translations and updates.

I’ve built out most of the translations and revisions support already, but it still needs polish and documentation.

Authentication

This is probably the next major decision. How do we handle API authentication? do we use OAuth? 1.0 or 2.0? Where do we handle actual user login/registration?… the entire app is going to be built on the API. At the moment I’m leaning towards OAuth 2.0, primarily because its what Swiftriver uses, and consistency between products is important. However OAuth 2.0 has some issues:

The editor for the spec withdrew saying OAuth 2 had failed

There are a few ways to mess up an implementation security wise

and one implementation isn’t guaranteed to be interoperable with another

That said the many almost-oauth APIs out there probably have more, and similar problems: rolling our own is not an option. OAuth 2 is probably still going to get a lot of use, and there are good resources appearing on how to do it right, and a couple of good oauth2 clients. One recommendation that stuck out was “If your API can require HTTPS, use OAuth 2.0 with bearer tokens. Otherwise, use OAuth 1.0a”. I need to dig into the details of this, but given deployers won’t always use SSL this is worth considering.

Stumbling blocks

In my last post I mentioned adding support for other databases, particularly PostgreSQL/PostGIS. I’ve already hit the first snag with this: minion migrations doesn’t handle other database engines at all. There are a few forks on github that try to solve this, but its mixed in with some other major changes. This isn’t a show stopper, but there’s some unpicking to be done and for now we’re concentrating on building a working API. If anyone has working PostGIS knowledge and whats to have a go at getting this working, grab the code, leave a note and hopefully send a pull request. I’m happy to walk you through the existing code and answer questions.