Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] API Design #151

Open
timlinux opened this issue Nov 28, 2023 · 3 comments
Open

[WIP] API Design #151

timlinux opened this issue Nov 28, 2023 · 3 comments
Labels

Comments

@timlinux
Copy link
Collaborator

timlinux commented Nov 28, 2023

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
Copy link
Collaborator Author

timlinux commented Nov 29, 2023

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
Copy link
Collaborator Author

timlinux commented Nov 29, 2023

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

  • indicators
  • code lists
  • codes

@timlinux
Copy link
Collaborator Author

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,)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants