From 7878b448a806289634f0ea79166b5221816b906e Mon Sep 17 00:00:00 2001 From: Emerson Rocha Date: Sun, 2 May 2021 06:32:14 -0300 Subject: [PATCH] CODV2API (#1): added draft of 5 endpoints --- CODV2API/CODV2API-eng.oas.yml | 46 ----- CODV2API/CODV2API-eng.openapi.yaml | 309 +++++++++++++++++++++++------ CODV2API/CODV2API-eng.raml.yml | 2 + 3 files changed, 255 insertions(+), 102 deletions(-) delete mode 100644 CODV2API/CODV2API-eng.oas.yml diff --git a/CODV2API/CODV2API-eng.oas.yml b/CODV2API/CODV2API-eng.oas.yml deleted file mode 100644 index a17e949..0000000 --- a/CODV2API/CODV2API-eng.oas.yml +++ /dev/null @@ -1,46 +0,0 @@ -swagger: "2.0" -info: - title: COD Services API - version: v2 -host: beta.itos.uga.edu -basePath: /CODV2API/api/v1 -schemes: - - https -paths: - /locations: - x-amf-description: | - List available locations(with metadata about each such as preferred name, iso codes, etc.) and lists of themes available in each location Returns: location name, iso_3, themes - get: - responses: {} - /locations/{pCode}: - x-amf-description: | - Location-level Listing of all themes and versions available for a location. LocationId in this case, represents the P-Code. P-Code representing a specific location. It is case insensitive.JSON - parameters: - - - name: pCode - required: true - in: path - type: string - get: - responses: {} - /themes: {} - /themes/cod-ab: {} - /themes/cod-ab/locations: {} - /themes/cod-ab/locations/{pCode}: - parameters: - - - name: pCode - required: true - in: path - type: string - /themes/cod-ab/locations/{pCode}/versions: - parameters: - - - name: pCode - required: true - in: path - type: string - get: - description: Provides metadata about a specific COD-AB version (number of levels, level names, notes about levels, number of units within each level, availability of geometry, version dates, etc.) with URLs to various downloadables and services. example - responses: {} - /themes/cod-ab/locations/{pCode}/versions/{versionId}: {} diff --git a/CODV2API/CODV2API-eng.openapi.yaml b/CODV2API/CODV2API-eng.openapi.yaml index be444ca..516d08b 100644 --- a/CODV2API/CODV2API-eng.openapi.yaml +++ b/CODV2API/CODV2API-eng.openapi.yaml @@ -1,7 +1,7 @@ # FILE: CODV2API-eng.openapi.yaml # LICENSE: Unlicense # -# ONLINE VERSION: https://editor.swagger.io/?url=https://hapi.etica.ai/HDX/CODV2API-eng.openapi.yaml +# ONLINE VERSION: https://editor.swagger.io/?url=https://hapi.etica.ai/CODV2API/CODV2API-eng.openapi.yaml # # README FIRST!: This file uses OpenAPI syntax (https://www.openapis.org/), # a de facto non-proprietary industry standard to document @@ -19,7 +19,7 @@ openapi: 3.0.3 # @see https://spec.openapis.org/oas/v3.1.0 info: - title: COD Version 2 API (English) + title: UN OCHA COD Version 2 API (English) description: | This resource, using [OpenAPI 3.0 specification](https://www.openapis.org/) @@ -76,81 +76,278 @@ servers: # and CKAN. For example, the file # https://github.com/teamdigitale/api-openapi-samples/blob/master/external-apis/api.daf.teamdigitale.it.yaml.src paths: + + # NOTE: the will not be documented here + # /current: + /locations: get: - parameters: - - in: query - name: limit - description: > - If given, the list of datasets will be broken into pages of at most - `limit` datasets per page and only one page will be returned at a time - required: false - schema: - type: integer - default: 250 - # NOTE: is possible to not use a default and display EVERYTING. - # But this can freeze user browser even if a 200kb response. - - in: query - name: offset + # description: > + # List available locations(with metadata about each such as preferred name, + # iso codes, etc.) and lists of themes available in each location Returns: + # location name, iso_3, themes + responses: + '200': description: > - When `limit` is given, the `offset` to start returning packages from - required: false - schema: - type: integer + List available locations(with metadata about each such as preferred + name, iso codes, etc.) and lists of themes available in each + location Returns: location name, iso_3, themes + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/LocationMetadataReply' + /locations/{pCode}: + parameters: + - $ref: '#/components/parameters/pCodePathParam' + + get: + # description: > + # List available locations(with metadata about each such as preferred name, + # iso codes, etc.) and lists of themes available in each location Returns: + # location name, iso_3, themes + responses: '200': description: > - Return a list of the names of the site’s datasets (packages). + List available locations(with metadata about each such as preferred + name, iso codes, etc.) and lists of themes available in each + location Returns: location name, iso_3, themes + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/LocationMetadataReply' + '500': + $ref: '#/components/schemas/Error500GenericReply' - See also: - - https://docs.ckan.org/en/2.9/api/#ckan.logic.action.get.package_list + # TODO: this endpint needs testing + # TODO: this endpint needs documentation + /themes/cod-ab/locations/{pCode}/versions/current: + parameters: + - $ref: '#/components/parameters/pCodePathParam' + get: + responses: + '200': + description: > + List available locations(with metadata about each such as preferred + name, iso codes, etc.) and lists of themes available in each + location Returns: location name, iso_3, themes content: application/json: schema: type: array items: - $ref: '#/components/schemas/CkanReply' - /tag_list: {} - # TODO: /tag_list - # https://docs.ckan.org/en/latest/api/index.html#ckan.logic.action.get.tag_list + $ref: '#/components/schemas/LocationMetadataReply' + '500': + $ref: '#/components/schemas/Error500GenericReply' - /tag_show: {} - # TODO: /tag_show - # https://docs.ckan.org/en/latest/api/index.html#ckan.logic.action.get.tag_show + # https://beta.itos.uga.edu/CODV2API/Help/Api/GET-api-v1-themes-cod-ab-locations-pCode-versions-versionId + /themes/cod-ab/locations/{pCode}/versions/{versionId}: + parameters: + - $ref: '#/components/parameters/pCodePathParam' + - $ref: '#/components/parameters/versionIdPathParam' + get: + responses: + '200': + description: > + Provides metadata about a specific COD-AB version (number of + levels, level names, notes about levels, number of units within + each level, availability of geometry, version dates, etc.) with + URLs to various downloadables and services. + example: /api/v1/themes/cod-ab/locations/GUI/versions/0.4 + content: + application/json: + # TODO: add exact response type + schema: + type: string + '500': + $ref: '#/components/schemas/Error500GenericReply' -components: - # NOTE: OpenAPI 3.0 seems to not allow use $ref outside schemas - # (but OpenAPI 3.1 allow it), but the teamdigitale/api-openapi-samples - # uses this as part of build scripts. We will keep it simple without - # use extra steps. - # responses: - # CkanResponse: - # description: >- - # Standard Ckan Reply. See http://docs.ckan.org/en/latest/api/index.html. + # https://beta.itos.uga.edu/CODV2API/Help/Api/GET-api-v1-themes-cod-ab-locations-pCode + /themes/cod-ab/locations/{pCode}: + parameters: + - $ref: '#/components/parameters/pCodeNeedsFixPathParam' + get: + responses: + '200': + description: > + Provides metadata about all COD-AB versions at a location + ( input iso location returns admin0 pcode, name, version number, + valid_from and valid_to with comments). The parameter takes unique + location identfier which is a string data type. + An /api/v1/themes/cod-ab/locations/sdn/ + + example: /api/v1/themes/cod-ab/locations/sdn/ JSON + content: + application/json: + # TODO: add exact response schema type (see example) + schema: + type: string + example: + { + "AllVersionsAtLocation": [ + { + "admin0Pcode": "sdn", + "admin0Name_ref": " Sudan", + "version": "Latest", + "valid_from": "2020-08-31T00:00:00", + "valid_to": "2021-08-31T00:00:00", + "comments": null + }, + { + "admin0Pcode": "sdn", + "admin0Name_ref": " Sudan", + "version": "Latest", + "valid_from": "2020-08-31T00:00:00", + "valid_to": "2021-08-31T00:00:00", + "comments": null + } + ] + } + '500': + $ref: '#/components/schemas/Error500GenericReply' + # https://beta.itos.uga.edu/CODV2API/Help/Api/GET-api-v1-themes-cod-ab-locations-pCode-versions-current-level-z-x-y.pbf + + # TODO: discover some z b y that would allow test the result. + /themes/cod-ab/locations/{pCode}/versions/current/{level}/{z}/{x}/{y}.pbf: + parameters: + - $ref: '#/components/parameters/pCodeNeedsFixPathParam' + - name: "level" + in: path + description: "Individual level (1 of 0-n)" + required: true + schema: + type: string + example: "1" + - name: "z" + in: path + description: "(FIXME: add description)" + required: true + schema: + type: string + example: "1" + - name: "x" + in: path + description: "(FIXME: add description)" + required: true + schema: + type: string + example: "1" + - name: "y" + in: path + description: "(FIXME: add description)" + required: true + schema: + type: string + example: "1" + get: + responses: + '200': + description: > + Retrieve the vector tiles in protobuf (.pbf) format for input + country (Pcode) and individual level ( 1 of 0-n). pbf + content: + application/json: + # TODO: add exact response schema type (see example) + schema: + type: string + '500': + $ref: '#/components/schemas/Error500GenericReply' + + # FIXME: the https://beta.itos.uga.edu/CODV2API/api/v1/themes/cod-ab/locations/SDN/versions/current/1/1/1/1.pbf + # return 200 OK (not something like HTTP/1.1 400 Bad Request) + # and it's content is text/html, not someting like JSON. + # HTTP/1.1 200 OK + # Content-Type: text/html; charset=utf-8 + # + # Cannot GET /services/postgis/sdn_adm1/wkb_geometry/vector-tiles/1/1/1.pbf?fields=admin0name_en,admin0pcode,admin1name_en,admin1pcode + + # TODO: https://beta.itos.uga.edu/CODV2API/Help/Api/GET-api-v1-themes-cod-ab-locations-pCode-versions-current-format-level + # TODO: https://beta.itos.uga.edu/CODV2API/Help/Api/GET-api-v1-Themes + # TODO: https://beta.itos.uga.edu/CODV2API/Help/Api/GET-api-v1-themes-cod-ab-Lookup-latlng-latlong-wkid-level + # TODO: https://beta.itos.uga.edu/CODV2API/Help/Api/GET-api-v1-themes-cod-ab-lookup-level-iso2 + +components: schemas: - CkanReply: - # From teamdigitale/api-openapi-samples + LocationMetadataReply: + # https://beta.itos.uga.edu/CODV2API/Help/Api/GET-api-v1-locations + # title: | + # List available locations (with metadata about each such as preferred + # name, iso codes, etc.) and lists of themes available in each location + # Returns: location name, iso_3, themes. type: object required: - - result - - success - - help + - location_iso + - location_name + - Themes properties: - success: + location_iso: type: string - result: - anyOf: - - type: object - - type: array - error: - type: object - help: + minLength: 3 + maxLength: 3 + location_name: type: string - format: url + Themes: + type: array + items: + enum: + - "Administrative Boundary" + - "Population Statistics" status: - type: boolean + type: string enum: - - true - - false + - OK + # TODO: ask when is not OK? + total: + type: number + + Error500GenericReply: + type: object + required: + - $id + - message + properties: + "$id": + type: string + message: + type: string + example: + { + "$id": "1", + "message": "An error has occurred." + } + + parameters: + pCodePathParam: + name: pCode + in: path + description: "P-code (Place Code) is (TODO: ADD SHORT DESCRIPTION)" + required: true + schema: + type: string + example: "HN01" + + # FIXME: the https://beta.itos.uga.edu/CODV2API/Help/Api/GET-api-v1-themes-cod-ab-locations-pCode + # says its a P-Code, but seems to be an ISO3 country code. We + # need to check this. + pCodeNeedsFixPathParam: + name: pCode + in: path + description: "(TODO: ADD SHORT DESCRIPTION)" + required: true + schema: + type: string + example: "SDN" + + versionIdPathParam: + name: versionId + in: path + description: "(TODO: ADD SHORT DESCRIPTION)" + required: true + schema: + type: integer \ No newline at end of file diff --git a/CODV2API/CODV2API-eng.raml.yml b/CODV2API/CODV2API-eng.raml.yml index eb1db3c..aeba0bf 100644 --- a/CODV2API/CODV2API-eng.raml.yml +++ b/CODV2API/CODV2API-eng.raml.yml @@ -3,6 +3,8 @@ # FILE: CODV2API-eng.raml --- +# NOTE: this file is deprecated, use CODV2API-eng.openapi.yaml + title: COD Services API version: v2 # baseUri: https://beta.itos.uga.edu/CODV2API/api/{version}