Mandatory Exercises

Mandatory Assignment 2

1
2
3
4
5

The Population API

Introduction

We have developed an API for this assignment that contains data from the World Bank development indicators dataset. To prepare you for working with DHIS2 we've designed the API to resemble the DHIS2 API.

If REST APIs are a new concept for you, here's a helpful video:

Querying the API

You can query the API by visiting https://in5430-api.onrender.com/api in your browser or by using an API client like postman.

https://in5430-api.onrender.com/api

The API returns data in a JSON format. Here's a video explaining JSON:

Each API response includes a pager and a results dictionary. The pager dictionary contains metadata on the results while the results object contains an array of dictionaries containing data about countries.

{
    "pager": {
        "page":1,
        "pageCount":22,
        "pageSize":10,
        "total":215
        },
    "results": [{
            "Continent": "Asia",
            "ContinentCode": "AS",
            "Country": "Afghanistan",
            "CountryCode": "AFG",
            "Population": 38041754,
            "PopulationGrowth": 2.31},
            {...},
            {...},
            {...}]
    }

REST APIs usually let you add parameters to the end of the a query with a ?:

https://in5430-api.onrender.com/api?page=1

You can add several parameters with an &:

https://in5430-api.onrender.com/api?page=2&pageSize=50

Page parameters

Most APIs use pagination when returning a lot of data. Pagination is splitting the results up into "pages" that contain a certain amount of results and allowing access to the following pages through the page parameter:

https://in5430-api.onrender.com/api?page=2

You can change the page size with the pageSize parameter. The default page size is 10.

https://in5430-api.onrender.com/api?pageSize=50

Finally, it is possible to disable paging and return all results instead with the paging parameter. Don't do this if you don't need all of the data because it's a bad practice to waste resources.

https://in5430-api.onrender.com/api?paging=false

Order parameter

The order parameter decides how the results should be sorted. You can sort by any value in the results object like Population, Country or Continent (which is case sensitive). You can choose an ascending sort (from smallest to largest) or a descending sort (from largest to smallest) by adding :ASC or :DESC after the column name.

https://in5430-api.onrender.com/api?order=Population:ASC
https://in5430-api.onrender.com/api?order=PopulationGrowth:DESC

Search parameter

The search parameter searches for country names that contain the search term and returns a list with all matches:

https://in5430-api.onrender.com/api?search=island
https://in5430-api.onrender.com/api?search=z

Filter parameter

It's possible to filter on specific country values. In contrast to searching it requires an exact match for it to return any results. The filter parameter is case-sensitive so you need to search for "Norway" and not "norway". Similar to the order parameter you can filter by any column returned in the results object:

https://in5430-api.onrender.com/api?Country=Norway
https://in5430-api.onrender.com/api?ContinentCode=EU

You can filter on several matches at the same time by adding successive values with a ,

https://in5430-api.onrender.com/api?Country=Norway,Sweden
PrevNext