omulosi/ireporter

A web application for fighting corruption by providing means for exposing it to general public/relevant authorities. Also allows reporting on things that need government intervention.

iReporter API

iReporter API is a web service that provides API endpoints for clients to create, view edit and delete incident records. An incident record can either be a red-flag(an incident linked to corruption) or an intervention (a call for government agency to intervene).

Link to Hosted demo

To run the API

first clone this repo to your machine

git clone [email protected]:Omulosi/iReporter.git

then change the directory to the project directory

cd iReporter

then move to the develop branch git checkout develop

to make sure all the project dependencies are installed, create a virtual environment and install the packages there.

• to create a virtual enviroment called venv run

  python3 -m venv venv

• to activate the enviroment, run

  source venv/bin/activate

then install all packages for the project by running the following command

pip install -r requirements.txt

this assumes pip is already installed

running the app locally

To test our project set the following environment variable

export FLASK_APP=run.py

then do

flask run

To use the API, you have to be signed up and/or logged in. The API uses JWT tokens to secure endpoints.

To signup, open the following link using one of the methods described below under the Testing the API enpoints heading.

`<host>/api/v2/auth/signup`

host, here, can either be the localhost(127.0.0.1), if you are running the app locally or the heroku root where the API is hosted.

you will be required to supply your username and password and optionally provide such values as your email, phone number, firstname or lastname.

the response is a json formatted output containing an access token and a refresh token. These tokens will be used to authenticate a given user and to authorize the user to access all the protected endpoints.

you could also obtain the tokens by logging in to the API if the token gets expired. Use the following endpoint

    `<host>/api/v2/auth/login`

the response will be a json formatted output containing the access and refresh token

the refresh token is used to 're-login' to the API without going the whole way of providing a username and a password again. simply provide it the Authorization header the same way you access the other endpoints and continue using the access token returned to interact with the API.

the refresh endpoint is as shown below

    `<host>/api/v2/auth/refresh`

the API also provides means for logging out a user. Simply issue a delete request to the /api/v2/auth/logout endpoint. The accessing token will be revoked and will no longer be available for use.

After authentication, use the access tokens to access all the protected endpoints.

Testing the API endpoints

the project implements the following endpoints

Method	API Endpoint	Description
GET	/red-flags	Displays a list of all the red-flag records
POST	/red-flags	Creates a new red-flag record
GET	/red-flags/	Display a specific record given a ID
DELETE	/red-flags/	Deletes a specific record given an ID
PATCH	/red-flags//location	Edits the location field of a red-flag record
PATCH	/red-flags//comment	Edits the comment field of a red-flag record
GET	/interventions	Displays a list of all the intervention records
POST	/interventions	Creates a new intervention record
GET	/interventions/	Display a specific record given a ID
DELETE	/interventions/	Deletes a specific record given an ID
PATCH	/interventions//location	Edits the location field of an intervention record
PATCH	/interventions//comment	Edits the comment field of a intervention record
POST	/auth/signup	registers a user
POST	/auth/login	logs in to the API
DELETE	/auth/logout	revokes an authentication token
POST	/auth/refresh	returns a new access token
DELETE	/interventions/	Deletes a specific record given an ID
GET	/users//red-flags	returns all red-flags for a particular user
GET	/users//interventions	returns all interventions for a particular user

The endpoints can be tested using Postman, HTTPie (a command line http client), or curl.

Sample payload data for testing

Below are sample payload data you can use to test the endpoints

{'location': '-1.2, 37'}

{'comment': 'judges soliciting for bribes'}

{'status': 'resolved'}

All are strings and can be passed in as key value pairs in API requests. Check below for examples.

More sample payloads will be added as more endpoints get implemented

Test Using Postman (Recommended)

With the project running locally, use the Postman service to test the endpoints by prepending each endpoint in the table above to the base url http://127.0.0.1:5000/api/v2/.

For endpoints that require user/client input, Postman provides an easy to use graphical interface for supplying the values as key-value pairs in a header. It also an easy to use authentication field where the token can pasted into before a request is issued.

Test Using HTTPie

Install HTTPie client by running

pip install httpie

This assumes you have already activated your virtual environment and installed all dependencies

Run the the application from the command line using flask run then in another terminal(from the same repo), run the following commands(the commands given are only for illustration purposes):

$http GET api/v2/interventions "Authorization:Bearer <token>"

$http POST api/v2/red-flags location='23,34' comment='bribery' "Authorization:Bearer <token>"

$http GET api/v2/interventions/1 "Authorization:Bearer <token>"

$http DELETE api/v2/interventions/1

$http PATCH api/v2/interventions/1/location location='45,34'

$http PATCH api/v2/interventions/1/comment comment='police brutality'

Remember to prepend the host the commands above. These are only sample requests and do not exhaustively cover all the possible requests supported by the API

for more information, checkout the documentation

Documentation

View the documentation here