portais-ckan-brasil (#4): rascunho inicial, baseado no HDX/HDX-eng.op…

…enapi.yaml

locum/BR/portais-ckan-brasil/openapi.yaml

@@ -0,0 +1,130 @@
+# FILE:            locum/BR/portais-ckan-brasil/openapi.yaml
+# LICENSE:         Unlicense
+#
+# ONLINE VERSION:  https://editor.swagger.io/?url=https://hapi.etica.ai/locum/BR/portais-ckan-brasil/openapi.yaml
+#
+# README FIRST!:   This file uses OpenAPI syntax (https://www.openapis.org/),
+#                  a de facto non-proprietary industry standard to document
+#                  APIs.
+#                  Consider as starting point:
+#                    - Use this online editor https://editor.swagger.io/
+#                    - Check this https://openapi.tools/ for compatible tools
+
+
+openapi: 3.0.3
+# NOTE: the current file, as 2021-05-01, uses OpenAPI 3.0 because 3.1 still too
+#       new (released 2021-02-15). But some comments already consider future
+#       upgrade.
+# @see https://spec.openapis.org/oas/v3.0.3
+# @see https://spec.openapis.org/oas/v3.1.0
+
+info:
+  title: Portais CKAN de dados abertos do Brasil
+  description: "TODO: add description"
+  version: "3" # 3 because CKAN uses 3, see https://docs.ckan.org/en/2.9/api/
+  # termsOfService: https://data.humdata.org/about/terms
+  # license:
+  #   name: Several license types
+  #   url: https://data.humdata.org/about/license
+  # contact:
+  #   name: Centre for Humanitarian Data
+  #   url: https://centre.humdata.org/contact-us/
+  #   email: [email protected]
+  # NOTE: The 'info:'' group is based on HDX website. The "Unofficial" is
+  #       added to avoid confusion individuals contributing via HXL-CPLP, an
+  #       HXL regional user group, be part of HDX.
+  #       The close to "official" documentation is likely to be:
+  #         - https://docs.ckan.org/en/latest/api/index.html
+  #         - https://data.humdata.org/faq
+  #       The "English version" on title is because one idea of HXL-CPLP is
+  #       eventually encourage localized translations.
+
+servers:
+  - url: https://dados.gov.br/api/3/action
+    description: HDX Production server
+  - url: https://data.humdata.org/api/3/action
+    description: HDX Production server
+
+
+# NOTE: for maintainers, the Team Digitale have a few references about OpenAPI
+#       and CKAN. For example, the file
+# https://github.com/teamdigitale/api-openapi-samples/blob/master/external-apis/api.daf.teamdigitale.it.yaml.src
+paths:
+  /package_list:
+    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: >
+            When `limit` is given, the `offset` to start returning packages from
+          required: false
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: >
+            Return a list of the names of the site’s datasets (packages).
+
+            See also:
+              - https://docs.ckan.org/en/2.9/api/#ckan.logic.action.get.package_list
+          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
+
+  /tag_show: {}
+  # TODO: /tag_show 
+  # https://docs.ckan.org/en/latest/api/index.html#ckan.logic.action.get.tag_show
+
+
+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.
+
+  schemas:
+    CkanReply:
+      # From teamdigitale/api-openapi-samples
+      type: object
+      required:
+        - result
+        - success
+        - help
+      properties:
+        success:
+          type: string
+        result:
+          anyOf:
+            - type: object
+            # - type: array
+        error:
+          type: object
+        help:
+          type: string
+          format: url
+        status:
+          type: boolean
+          enum:
+            - true
+            - false