Skip to main content

The Taarifa API for managing resources and requests

Project description

Background

Taarifa is an open source platform for the crowd sourced reporting and triaging of infrastructure related issues. Think of it as a bug tracker for the real world which helps to engage citizens with their local government.

Taarifa was founded at the 2011 London WaterHackathon, Winner of the 2013 Sanitation Hackathon, finalist at the 2014 Barcelona World Mobile Congress, and has been deployed in Uganda, Ghana, and Tanzania.

The API

The API forms the core of the Taarifa platform. It provides a RESTful API (built on Flask and Eve) that clients can interact with to create and triage “bug reports” relating to public infrastructure (e.g., the public toilet is broken).

To understand the API it is important to clarify some terminology:

  • service: a service provided by some authority (e.g. electricity, water, road cleaning, …)

  • facility: category of physical infrastructure (e.g. power lines, water pipes, road network, …)

  • resource: particular addressable piece of infrastructure (e.g. Church Street, the waterpoint at (23.44,-5.87))

  • request: a ticket/issue/report made by a citizen about a particular resource, service, or both

Aside: Those familiar with Open311 will recognize the terminology and semantics. While the Taarifa API is not fully Open311 compliant yet, this is on the roadmap.

Taarifa API provides a way for clients to create services, facilities, resources, and requests dynamically (at runtime). In particular the features it provides include:

  • defining new service/facility/resource/request schemas

  • automatic validation that submitted service/facility/… instances conform to the schema

  • versioning / history to track changes to resources and requests

Distributions

The goal is to have different distributions or flavours of Taarifa, built on top of the core API. The main one is currently the Taarifa Waterpoints distribution.

Installation

Ensure you have installed Python 2.7, pip >= 1.5 and MongoDB 3.0 and that the MongoDB server mongod is running.

Install virtualenv and virtualenvwrapper (you might need admin rights for this):

pip install virtualenv virtualenvwrapper

Set up virtualenvwrapper according to your shell and create a virtualenv:

mkvirtualenv TaarifaAPI

If you already created the virtualenv, activate it:

workon TaarifaAPI

Clone the repository:

git clone https://github.com/taarifa/TaarifaAPI

Change into the directory and install the requirements:

cd TaarifaAPI
pip install -r requirements.txt

Install the package itself:

python setup.py develop

Usage

Start the API server from the TaarifaAPI directory by running:

python taarifa_api/taarifa_api.py

This starts the API server using a local MongoDB database and requires MongoDB to be running locally. To use a remote database, export the environment variable MONGOLAB_URI with a connection URI of the form

mongodb://[username:password@]host[:port][/[database]]

To check things are working, open a browser and navigate to:

http://localhost:5000/api

This should show you the various endpoints available. To see the API documentation go to:

http://localhost:5000/docs

Contribute

There is still much left do do and Taarifa is currently undergoing rapid development. To get started send a message to the taarifa-dev mailinglist and check out the github issues. We use the github pull request model for all contributions. Refer to the contributing guidelines for further details.

Project details


Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page