[WIP] API Design

[timlinux]

Overview

This issue describes a proposed API for GeoSight. What do we want to achieve
with the API? Some possibilities:

• ⬆️️ Push data to GeoSight
  • Use case: App integrations to push data from other places
  • Insert indicator values (already in swagger)
  • Replace related tables (in future replace / add partial data in the
    table)
• ⬇️ Pull data from GeoSight
  • Use case: Get data from GeoSight to display in 3rd party app
  • Lower priority than push?
• 🛠️ GeoSight Content Management
  • Configure projects etc.
  • Use case: Alternative management UI, focus on import / export actions which allow backing up, migrating, batch creation, integrations with SDMX etc.

Our API will address two areas on concern:

• data - these are actual information units used to drive the visualisation of the platform
• indicator values - these are admin area / geography linked observations (indicator) for a specific date and time
• related tables - these are detailed structured tables which allow the creation of 1:m relationships between indicator values and additional data associated with that indicator
• content - these are the declared indicators, projects, styles etc. that have been created on the system by our users (creators / content managers).

API

/api/v1/projects/

• 📒 Description:
  • A detailed definition of a project.
• ⬇️ Parameters:
  • none
• ⬆️ Returns list:
  • results {array}
    • id
    • name
    • description
    • slug
    • thumbnail
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

For the elements of a project that are represented as lists, use the following
calls:

/api/v1/projects/{id}/indicators/

• 📒 Description:
  • A paginated list of indicators associated with a project.
• ⬇️ Parameters:
  • none
• ⬆️ Returns:
  • results {array}:
    • id
    • name
    • description
    • slug
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

/api/v1/projects/{id}/context-layers/

• 📒 Description:
  • A paginated list of context layers associated with a project. Context
    layers are spatial overlays that can be shown in conjunction with
    indicators and base maps.
• ⬇️ Parameters:
  • none
• ⬆️ Returns:
  • results {array}:
    • id
    • name
    • description
    • slug
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

/api/v1/projects/{id}/basemaps/

• 📒 Description:
  • A paginated list of base map layers associated with a project. Context
    layers are spatial underlays that can be shown in conjunction with
    indicators and context layers maps. Base maps are always shown in the
    background, behind all other layers. Only a single base map may be
    visible at any time.
• ⬇️ Parameters:
  • none
• ⬆️ Returns:
  • results {array}:
    • id
    • name
    • description
    • slug
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

/api/v1/projects/{id}/related-tables/

• 📒 Description:
  • Related tables are tables of auxiliary information. that can be attached
    to an indicator.
• ⬇️ Parameters:
  • none
• ⬆️ Returns:
  • results {array}:
    • id
    • name
    • description
    • slug
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

Indicators

/api/v1/indicators/

• 📒 Description:
  • A paginated list of indicator.
• ⬇️ Parameters:
  • project_slug={project_slug}
  • project_id={project_id}
  • name_contains={string}
  • ...
• ⬆️ Returns:
  • results {array}:
    • id
    • name
    • description
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

/api/v1/indicators/{id}/

• 📒 Description:
  • A detailed indicator.
• ⬇️ Parameters:
  • project_slug={project_slug}
  • project_id={project_id}
  • name_contains={string}
  • ...
• ⬆️ Returns:
  • id
  • name
  • description
  • short_code
  • type

/api/v1/indicators/{id}/data

• 📒 Description:
  • A paginated list of data of an indicator.
  • Reuse data browser with fixed filtered indicator.
• ⬇️ Parameters:
  • date_gte={date_gte}
  • date_lte={date_lte}
  • ....
• ⬆️ Returns:
  • results {array}:
    • id
    • indicator
    • indicator_id
    • indicator_shortcode
    • value
    • permission
    • date
    • geom_id
    • geometries {array}:
      • dataset_uuid
      • dataset_name
      • name
      • admin_level
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

/api/v1/indicators/{id}/categories

• 📒 Description:
  • A paginated list of data of category of indicators.
• ⬇️ Parameters:
  • node
• ⬆️ Returns:
  • results {array}:
    • name
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

Data Browser (Indicator Value)

/api/v1/data-browser/

• 📒 Description:
  • A paginated list of indicator data.
• ⬇️ Parameters:
  • indicator_id={indicator_id}
  • indicator_id__in={array}
  • ....
• ⬆️ Returns:
  • results {array}:
    • id
    • indicator
    • indicator_id
    • indicator_shortcode
    • value
    • permission
    • date
    • geom_id
    • geometries {array}:
      • dataset_uuid
      • dataset_name
      • name
      • admin_level
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

Context Layer

/api/v1/context-layers/

• 📒 Description:
  • A paginated list of context layer.
• ⬇️ Parameters:
  • project_slug={project_slug}
  • project_id={project_id}
  • name_contains={string}
  • ...
• ⬆️ Returns:
  • results {array}:
    • id
    • name
    • description
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

/api/v1/context-layers/{id}/

• 📒 Description:
  • A detailed context layer.
• ⬇️ Parameters:
  • project_slug={project_slug}
  • project_id={project_id}
  • name_contains={string}
  • ...
• ⬆️ Returns:
  • id
  • name
  • description
  • URL ❓️ Check with Jan
  • Others ❓️ Check with Jan

Basemap

/api/v1/basemaps/

• 📒 Description:
  • A paginated list of basemap.
• ⬇️ Parameters:
  • project_slug={project_slug}
  • project_id={project_id}
  • name_contains={string}
  • ...
• ⬆️ Returns:
  • results {array}:
    • id
    • name
    • description
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

/api/v1/basemaps/{id}/

• 📒 Description:
  • A detailed basemap.
• ⬇️ Parameters:
  • project_slug={project_slug}
  • project_id={project_id}
  • name_contains={string}
  • ...
• ⬆️ Returns:
  • id
  • name
  • description
  • URL ❓️ Check with Jan
  • Others ❓️ Check with Jan

Related Table

/api/v1/related-tables/

• 📒 Description:
  • A paginated list of related table.
• ⬇️ Parameters:
  • project_slug={project_slug}
  • project_id={project_id}
  • name_contains={string}
  • ...
• ⬆️ Returns:
  • results {array}:
    • id
    • name
    • description
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

/api/v1/related-tables/{id}/

• 📒 Description:
  • A detailed related tables.
• ⬇️ Parameters:
  • none
• ⬆️ Returns:
  • id
  • name
  • description

/api/v1/related-tables/{id}/data/

• 📒 Description:
  • List of data of a related table.
• ⬇️ Parameters:
  • none
• ⬆️ Returns:
  • results {array}:
    • ...
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

Code List

/api/v1/code-list/

• 📒 Description:
  • A paginated list of code list.
• ⬇️ Parameters:
  • name_contains={string}
• ⬆️ Returns:
  • results {array}:
    • id
    • name
    • description
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

/api/v1/code-list/{id}

• 📒 Description:
  • A detailed code list.
• ⬇️ Parameters:
  • none
• ⬆️ Returns:
  • id
  • name
  • description
  • codes {Array}:
    • id
    • name
    • value

/api/v1/code-list/{id}/code

• 📒 Description:
  • List of code of code list.
• ⬇️ Parameters:
  • none
• ⬆️ Returns:
  • results {array}:
    • id
    • name
    • value
  • count - number of records
  • page - current page
  • page_count - count of pages
  • next - number of next page
  • previous - number of previous page

/api/v1/code-list/{id}/code/{code_id}

• 📒 Description:
  • A detailed code of code list.
• ⬇️ Parameters:
  • none
• ⬆️ Returns:
  • id
  • name
  • value

[timlinux]

Priorities from Jan and rationale:

Indicators

• list indicators
• add indicator - supports batch import of indicators e.g. from another platform. The format for PUT should be the same as the filtered list of indicators returned as a filtered. Focus on simple properties first:
  • name (unique),
  • description,
  • source,
  • short_code (unique),
  • category (see category API),
  • units,
  • type (int, float, category),
  • type min (for in and float types),
  • type max (for int and float types),
  • code_list_id (for category type only),
  • aggregation_type - disabled for now, set to NOT ALLOW *
  • aggregation_
  • style - disabled for now, set to NULL and DEFAULT style will be used for now *
  • label - disabled for now, set to NULL and DEFAULT label will be used for now *

*In future we will add formal api for aggretation, style, label CRUD operations.

Code Lists

• list codelists
• add codelist - currently only managed via django API, which is klunky. Also when we have long code lists it is manual and labour intensive to manage by hand, whereas it is a good candidate for automation.
• list codes for codelist
• add code to codelist

[timlinux]

Focus for the hackfest coming up in Dec (make separate tickets for this):

• indicators
• code lists
• codes

[timlinux]

TODO

• Indicators need short code and all attributes
• context layers need all attributes
• change references of slug to match naming convention in the UI e.g. slug
• basemaps layers need all attributes
• related tables need a data endpoint
• indicator need more parameters (name contains, description contains, etc,)