OpenAPI Gisco yaml

gisco.yaml

#
# Questo e' un progetto d'esempio in formato OpenAPI 3.0 API Starter Kit.
#
# Stai per sviluppare un API? Segui attentamente questo template e
#   potrai integrarla facilmente in Developers Italia.
#
# Se usi componenti in modo ricorrente, yaml
#   permette di definirle e riusarle.
#   Puoi metterle nell'oggetto x-commons e rimuoverlo
#   prima di pubblicarle.
x-commons:
  ratelimit-headers: &ratelimit-headers
    X-RateLimit-Limit:
      $ref: '#/components/headers/X-RateLimit-Limit'
    X-RateLimit-Remaining:
      $ref: '#/components/headers/X-RateLimit-Remaining'
    X-RateLimit-Reset:
      $ref: '#/components/headers/X-RateLimit-Reset'
  common-responses: &common-responses
    '400':
      $ref: '#/components/responses/400BadRequest'
    '429':
      $ref: '#/components/responses/429TooManyRequests'
    '503':
      $ref: '#/components/responses/503ServiceUnavailable'
    default:
      $ref: '#/components/responses/default'

openapi: 3.0.0
info:
  version: "2.0.0"
  title: |-
    Gisco API.
  x-summary: >-
    EU Gisco Maps (nuts, coastal lines)
  description: |
    #### Documentazione
    The main goal of GISCO's various activities and long-term projects is to better integrate statistical and geospatial information at the EU level.

  termsOfService: 'https://ec.europa.eu/eurostat/web/gisco/geodata/reference-data/administrative-units-statistical-units'
  # Chi posso contattare per informazioni sul servizio e sul suo stato?
  contact:
    email: robipolli@gmail.com
    name: Roberto Polli
    url: https://twitter.com/ioggstream
  # L'audience delle API. Attualmente e' definito solamente
  #   la tipologia `public`.
  x-audience:
    - public
  # Ogni API deve avere un UUID, invariante nel tempo e
  #   rispetto al `title`.
  x-api-id: 00000000-0000-0000-0000-000000000000
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

  # Per dare indicazioni sul ciclo di vita dell'API
  # si puo' usare un parametro come:
  x-lifecycle:
    published: 1970-01-01
    deprecated: 2050-01-01
    retired: 2050-06-01
    maturity: published

# Una lista di `tag` utili a raggruppare le varie operazioni
#   eseguite dalle API. Ogni `tag` puo' referenziare un link
#   alla sua descrizione.
tags:
  - name: public
    description: Retrieve informations
    externalDocs:
      url: http://docs.my-api.com/pet-operations.htm
# Uno o piu' server di erogazione.
#   Puo' essere utile indicare gli indirizzi di collaudo,
#   sviluppo e test.
#   Di seguito mostriamo come indicare se il server
#   e' una sandbox o meno con dei tag custom.
servers:
  - description: Development server
    url: https://gisco-services.ec.europa.eu/distribution/v2
#
# Qui vanno tutti i path.
#
paths:
  /themes.json:
    get:
      description: |-
        get all themes
      responses:
        "200":
          description: |-
            Ok
          content:
            application/json:
              schema:
                type: object

  /{theme}/datasets.json:
    get:
      description: |-
        Return all the coastline files in the set.
      parameters:
        - $ref: '#/components/parameters/Theme'
      responses:
        "200":
          description: Ok
          content:
            application/json:
              schema:
                example:
                   coastline-2010: {
                      date: "01/01/2012",
                      documentation: "coastline-2010-release-notes.txt",
                      files: "coastline-2010-files.json",
                      hashtag: "",
                      metadata: { },
                      packages: "coastline-2010-packages.json",
                      title: "Coastal lines 2010",
                      titleMultilingual: {
                        de: "Küstenlinien 2010",
                        en: "Coastal lines 2010",
                        fr: "Lignes de côte 2010"
                      }
                   }

                type: object
                x-patternProperties:
                  "coastline-[0-9]{4}":
                    $ref: '#/components/schemas/Datafile'

  /{theme}/{indexfile}:
    get:
      parameters:
      - $ref: '#/components/parameters/Theme'
      - $ref: '#/components/parameters/IndexFile'
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                type: object
  /{theme}/{fmt}/{id}.{fmt}:
    get:
      summary: Return the requested data.
      description: |
        Return the requested data.
      operationId: get_data
      tags:
        - data
      parameters:
      - $ref: '#/components/parameters/Id'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/Theme'
      responses:
        <<: *common-responses
        '200':
          description: |
            Il server ha ritornato il timestamp.
          headers:
            <<: *ratelimit-headers
          content:
            application/json:
              schema:
                type: object
components:
  examples:
    ThemesExample:
      value:
        coas:
          title: Coastal lines
          titleMultilinual:
            de: Küstenlinien
            en: Coastal lines
            fr: Lignes de côte
        communes:
          title: Communes
          titleMultilinual:
            de: Gemeinden
            en: Communes
            fr: Communes
        countries:
          title: Countries
          titleMultilinual:
            de: Staaten
            en: Countries
            fr: Pays
        lau:
          title: Local Administrative Units
          titleMultilinual:
            de: Local Administrative Units
            en: Local Administrative Units
            fr: Local Administrative Units
        nuts:
          title: NUTS
          titleMultilinual:
            de: NUTS
            en: NUTS
            fr: NUTS
        urau:
          title: Urban Audit
          titleMultilinual:
            de: Städte-Audit
            en: Urban Audit
            fr: Audit Urbain

  parameters:
    Theme:
      in: path
      name: theme
      required: true
      schema:
        type: string
        enum:
          - coas
          - communes
          - lau
          - nuts
          - urau
    Format:
      name: fmt
      in: path
      required: true
      schema:
        type: string
        enum:
          - csv
          - geojson
          - pfb
          - svg
          - topojson
    IndexFile:
      name: indexfile
      in: path
      required: true
      schema:
        type: string
        example: coastline-2020-files.json
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string
        example: NUTS_BN_01M_2021_3035

  headers:
    X-RateLimit-Limit:
      $ref: 'https://teamdigitale.github.io/openapi/0.0.7/definitions.yaml#/headers/X-RateLimit-Limit'
    X-RateLimit-Remaining:
      $ref: 'https://teamdigitale.github.io/openapi/0.0.7/definitions.yaml#/headers/X-RateLimit-Remaining'
    X-RateLimit-Reset:
      $ref: 'https://teamdigitale.github.io/openapi/0.0.7/definitions.yaml#/headers/X-RateLimit-Reset'
    Retry-After:
      $ref: 'https://teamdigitale.github.io/openapi/0.0.7/definitions.yaml#/headers/Retry-After'

  responses:
    # Predefined error codes for this API
    400BadRequest:
      $ref: 'https://teamdigitale.github.io/openapi/0.0.7/definitions.yaml#/responses/400BadRequest'
    404NotFound:
      $ref: 'https://teamdigitale.github.io/openapi/0.0.7/definitions.yaml#/responses/404NotFound'
    429TooManyRequests:
      $ref: 'https://teamdigitale.github.io/openapi/0.0.7/definitions.yaml#/responses/429TooManyRequests'
    503ServiceUnavailable:
      $ref: 'https://teamdigitale.github.io/openapi/0.0.7/definitions.yaml#/responses/503ServiceUnavailable'
    default:
      $ref: 'https://teamdigitale.github.io/openapi/0.0.7/definitions.yaml#/responses/default'

  schemas:
    IndexFile:
      properties:
        csv: {}
        geojson: {}
        pbf: {}
        shp: {}
        topojson: {}

    Datafile:
      type: object
      required:
      - files
      - date
      - title
      properties:
        files:
          type: string
          example: coastline-2010-files.json
          default: nuts-2003-files.json
    Problem:
      $ref: 'https://teamdigitale.github.io/openapi/0.0.7/definitions.yaml#/schemas/Problem'