RSR_Partner API Write

Background information

For background information on the write API, see the read API documentation. In works in a similar manner.

Methods

The following methods are allowed:

• GET (see read API)
• POST for adding a new object to the database
• PUT for updating all fields of an existing object
• PATCH for updating a subset of the fields of an existing object
• DELETE for deleting an object

Example

Below is an example of a POST request to the API - it posts an indicator period update. This code uses Python and the requests library, but you can use a tool of your choice for doing this.

import json
import requests

URL = 'http://rsr.akvo.org/rest/v1/indicator_period_data_framework/?format=json&limit=100'
API_KEY = '<API_KEY>'

headers = {
    'content-type': 'application/json',
    'Authorization': 'Token {}'.format(API_KEY)
}
data = {
    "id": "new-1",
    "period": 6530,
    "user": 25213,
    "value": "12",
    "narrative": "",
    "text": "",
    "status": "D",
    "actual_value": 14,
    "disaggregations": []
}

r = requests.post(URL, data=json.dumps(data), headers=headers)
print(r.status_code)

Posting an image file

Here is an example that shows how to upload a file using the API

import requests

URL = 'https://rsr.akvo.org/rest/v1/indicator_period_data/10461/upload_file/?format=json'
API_KEY = <API_KEY>

headers = {
    'Authorization': 'Token {}'.format(API_KEY)
}

with open('/tmp/screenshot.png', 'rb') as f:
    files = {'file': f}
    data = {'type': 'photo'}
    r = requests.post(URL, data=data, files=files, headers=headers)

print(r.status_code)

The example uses Python's requests library, but here is what the headers sent by the library look like:

{
'Accept': '*/*',
'Accept-Encoding': 'gzip, deflate',
'Authorization': 'Token f8d1b07a04775012384b1fab20fa0a4adc815094',
'Content-Type': 'multipart/form-data; boundary=5f9174840e204ae0abbf9f2194316e2e',
}

and this is what the body of the request looks like

'--5f9174840e204ae0abbf9f2194316e2e\r\nContent-Disposition: form-data; name="type"\r\n\r\nphoto\r\n--5f9174840e204ae0abbf9f2194316e2e\r\nContent-Disposition: form-data; name="file"; filename="screenshot.png"\r\n\r\n\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x03\x1b\x00\x00\x02N\x08\x06\x00\x00\x00\xdf\xea\x1a9\x00\x00\x00\x04sBIT\x08\x08\x08\x08|\x08d\x88\x00 ... <snip> ... f\xb6\xcbz\x00\x14\xd7\x01|\x1c2\xf7\xc8\xedo\x98\x8a\xdc\xa5g\xed"-:\x8b+\xfeFD\x93\r\x14\xac\xa0\xaaqE-\xff?W\xef\xa9\xed\xa1\xc7\x1e\xa2\x00\x00\x00\x00IEND\xaeB`\x82\r\n--5f9174840e204ae0abbf9f2194316e2e--\r\n'

Exploring the API

To explore the various end-points of the API, you can use the Django Rest Framework explorer available at http://rsr.akvo.org/rest/v1/.

Let's say we would like to explore the API for adding an update (indicator period data) - looking at the API end-point listing available at http://rsr.akvo.org/rest/v1/ we see that the /rest/v1/indicator_period_data_framework seems like the best candidate.

We then click on the link for this end-point, and see web interface that lets us make GET and POST requests. The default is to make a GET request that returns a bunch of indicator period data entries (updates). If this seems to be taking too long, you can add an additional parameter limit to limit the number of entries being fetched in the first request. We navigate to http://rsr.akvo.org/rest/v1/indicator_period_data_framework?limit=1 to fetch a single update. If we are logged-in to RSR, at the bottom of the page we see a form for performing POST requests. There's a text area pre-filled with sample json data that we can modify to POST a new update.

API code of conduct

When using the Akvo RSR API, please respect our API Code of Conduct: http://www.akvo.org/web/akvo-rsr-api-code-of-conduct.