API Documentation

This page describe this website's free and open RESTful API's behavior

In order to be able to execute write operations, you first need to authenticate and obtain an API Key in your profile settings.

This key should be provided on each call in the X-API-KEY HTTP header.

API calls are subject to the same permissions than the web interface.

By example, you need to be part of the organization to modify one of its datasets.

Some method are paginated and always follow the same pattern. The object list is wrapped in a Page object.

You don't have to compute yourself the previous and next pages because the URLs are available in the response under the previous_page and next_page attributes. They will be set to null if there is no previous and/or next page.

Example:

{
    "data": [{...}, {...}],
    "page": 1,
    "page_size": 20,
    "total": 8,
    "next_page": "https://www.data4tunisia.org/api/endpoint/?page=2",
    "previous_page": null
}

All examples use the httpie and jq utilities for readability purpose. You don't need to use these tools in your code though, they're just helpers to better understand the API.

Verifying that httpie is working

Once httpie is installed, you can verify that it works as expected by typing that command in your shell:

$ http 'https://www.data4tunisia.org/api/1/organizations/?page_size=1'

It should return something in this vein:

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
... LOTS OF HEADERS ...

{
    "data": [
        {

            ... LOTS OF DATA ...

            "name": "OpenGovTN",
            "page": "https://www.data4tunisia.org/organizations/opengovtn/",
            "slug": "opengovtn",
            "uri": "https://www.data4tunisia.org/api/1/organizations/opengovtn/",
            "url": "https://www.facebook.com/groups/opengovtn/"
        }
    ],
    "next_page": "https://www.data4tunisia.org/api/1/organizations/?page=2&page_size=1",
    "page": 1,
    "page_size": 1,
    "previous_page": null,
    "total": "8"
}

This is very verbose and we don't need all that information yet. That's why we use jq.

Verifying that jq is working

Once jq is installed, you can verify that it works as expected by typing that command in your shell:

$ http 'https://www.data4tunisia.org/api/1/organizations/?page_size=1' | jq '.data[].name'

It should return something in this vein:

"OpenGovTN"

That's definitely better! Now that we're sure that it works as expected, let's shorten a bit the command line:

$ export API="https://www.data4tunisia.org/api/1/"

The previous command is now equivalent to the more readable (don't forget the quotes):

$ http $API'organizations/?page_size=1' | jq '.data[].name'

That's a good start, now let's dig into the API itself. We don't know it yet but we already fetched our first organization.

Browsing and retrieving data

You can retrieve a list of organization (filtered or not) or a unique organization. When you reach an endpoint, the default page size is 20. Let's fetch the first 20 organization from the API:

$ http $API'organizations/' | jq '.data[].name'

"OpenGovTN"
"Ministère de la culture"
"Banque mondiale"
"Eurostat"
"Democracy International Tunis"
"Fonds monétaire international"
"Ministère de l'Industrie, de l'Energie et des Mines"
"Institut national de la statistique"

That list is great to have but what if we want to walk through returned organizations? Let's fetch the first 5 organizations URIs:

$ http $API'organizations/?page_size=5' | jq '.data[].uri'

"https://www.data4tunisia.org/api/1/organizations/opengovtn/"
"https://www.data4tunisia.org/api/1/organizations/ministere-de-la-culture/"
"https://www.data4tunisia.org/api/1/organizations/banque-mondiale/"
"https://www.data4tunisia.org/api/1/organizations/eurostat/"
"https://www.data4tunisia.org/api/1/organizations/democracy-international/"

Now we'll be able to retrieve a unique organization thanks to the returned URI:

$ http $API'organizations/opengovtn/' | jq '.'

That's a lot of data to compute. Let's refine these data, if we want only metrics:

$ http $API'organizations/opengovtn/' | jq '.metrics'

{
 "nb_uniq_visitors": 0,
 "datasets": 7,
 "members": 2,
 "views": 0,
 "permitted_reuses": 0,
 "reuses": 5,
 "dataset_views": 0,
 "reuse_views": 0,
 "followers": 1,
 "resource_downloads": 0,
 "nb_hits": 0,
 "nb_visits": 0,
 
}

Or maybe just the name of the members of that organization:

$ http $API'organizations/opengovtn/' | jq '.members[].user.last_name'

"TROJETTE"
"Chouikha"

It's really up-to-you to retrieve the data that matters to your project. Do not hesitate to go through the jq's tutorial and manual if you want to browse the API through the command-line in depth.

Modifying and deleting data

Warning, you're entering a danger zone. Data modifications or deletions with the API are definitive and we don't provide any sandbox to test those prior executing (for now). Be aware of these responsibilities prior to use your great powers.

If you try to modify a resource without an authentication token, a 401 will be returned:

$ http PUT $API'organizations/organization-uri-x/'

HTTP/1.1 401 UNAUTHORIZED
... LOTS OF HEADERS ...

{
    "message": "Unauthorized",
    "status": 401
}

You need to specify your API Key (see above) and use the X-API-KEY HTTP header. If you try to modify a resource that you're not in control of, a 400 will be returned instead:

$ http PUT $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here

HTTP/1.1 401 UNAUTHORIZED
... LOTS OF HEADERS ...

{
    "message": "Invalid API Key",
    "status": 401
}

This is the message you will end up with if you specified the wrong API Key. There is another potential error message that you can encounter:

HTTP/1.1 403 FORBIDDEN
... LOTS OF HEADERS ...

{
    "message": "You do not have the permission to modify that object.",
    "status": 403
}

It occurs if you try to access a resource that you cannot edit with your credentials. If your Key is valid you should have something like this:

HTTP/1.1 200 OK
... LOTS OF HEADERS ...

{
    ...
}

But it didn't change anything! This is perfectly normal, we forgot to specify the right data to send to the server.

$ http PUT $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here name="Lorem ipsum" description="The quick brown fox jumps over the lazy dog." | jq '{name: .name, description: .description}'

{
  "name": "Lorem ipsum",
  "description": "The quick brown fox jumps over the lazy dog."
}

The resource has been modified with your new values. Finally, you can delete a resource with the appropriated HTTP verb (beware, no rollback is possible using the API at the moment):

$ http DELETE $API'organizations/organization-uri-x/' X-API-KEY:your.api.key.here

HTTP/1.0 204 NO CONTENT
... LOTS OF HEADERS ...

Once you did it, you can verify that it's effective issuing a GET against the previous URI:

$ http GET $API'organizations/organization-uri-x/'

HTTP/1.0 410 GONE
... LOTS OF HEADERS ...

{
    "message": "Organization has been deleted",
    "status": 410
}

Please consult the reference documentation below for further interactions with the API or ask us for questions related to it!