openapi: 3.0.3
info:
  title: API per l'accesso agli snapshot del database NeTEx del NAP
  description: |-
    Descrizione delle API dedicate all'accesso agli snapshot del database NeTEx del National Access Point italiano.
    Link utili:
    - [Profilo italiano NeTEx](https://netex-cen.eu/implementation/italian-implementation/)
    - [Data Catalog del NAP](https://nap-1926.it)
    - [Codici NUTS Italia](https://it.wikipedia.org/wiki/Nomenclatura_delle_unit%C3%A0_territoriali_per_le_statistiche_dell%27Italia)
  contact:
    email: sviluppo-nap@dueltv.com
  version: 1.0.0d2
servers:
  - url: https://nap-1926.it/nap/private/api/v1
tags:
  - name: shapshot
    description: Accesso agli snapshot nel NeTEx
paths:
  /netex/db/snapshot:
    get:
      tags:
        - snapshot
      summary: Catalogo degli snapshot disponibili
      description: Ritorna l'elenco degli snapshot disponibili per il download.
      operationId: getAllSnapshot
      parameters:
      - name: limit
        in: query
        description: massimo numero di righe da ritornare
        required: true
        schema:
          format: int32
          default: 10
          type: integer
      - name: offset
        in: query
        description: prima riga da ritornare
        required: true
        schema:
          format: int32
          default: 0
          type: integer
      responses:
        '200':
          description: Operazione terminata con successo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Snapshots'
        '403':
          description: Accesso negato
      security:
        - nap_auth:
            - read:snapshot
  /netex/db/snapshot/{shapshotId}:
    get:
      tags:
        - Snapshot per Id
      summary: Informazioni su uno specifico snapshot
      description: Ritorna le informazioni su uno snapshot identificato dallo `snapshotId` fornito
      operationId: getSnapshot
      parameters:
        - name: snapshotId
          in: path
          description: ID dello snapshot richiesto
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Snapshot'
        '404':
          description: Lo snapshot richiesto non esiste
      security:
        - nap_auth:
            - read:snapshot
components:
  schemas:
    Snapshot:
      type: object
      description: Metadati che descrivono uno snapshot del database NeTEx
      properties:
        snapshotId:
          description: identifica in modo univoco lo snapshot
          type: string
        netexLevel:
          format: int32
          description: Livello NeTEx dei dati contenuti nello snapshot
          type: integer
        areaType:
          description: tipo di area coperta dallo snapshot
          type: string
          allOf:
          - $ref: '#/components/schemas/NAPSnapshotAreaType'
        areaNutsCode:
          description: Codice NUTS dell'area coperta dallo snapshot
          type: string
        creationTime:
          description: Data e ora di creazione dello snapshot
          type: string
          format: ISO 8601 date-time
          example: "2023-09-07T19:50+01:00"
        modificationTime:
          description: data e ora di ultima modifica dei dati presenti nello snapshot.
            Se maggiore di `creationTime` significa che i dati contenuti nello snapshot
            sono stati aggiornati dopo la creazione di esso.            		  
          format: ISO 8601 date-time
          type: string
          example: "2023-09-07T19:50+01:00"
        downloadData:
          description: lista di url per il download dello snapshot compresso in formato zip. L'archivio diventa multivolume per dimensioni superiori al gigabyte.
          type: array
          items:
            $ref: '#/components/schemas/DownloadData'		
    NAPSnapshotAreaType:
      enum:
      - REGION
      - COUNTRY
      type: string        	
    DownloadData:    
      type: object	  
      properties:
        downloadLink:
          description: URL per il download dello snapshot
          type: string
        integrityHash:
          description: "SHA-256 del contenuto del file compresso, fornito allo scopo di verificarne l'integrità"
          type: string
  securitySchemes:
    nap_auth:
      type: oauth2
      flows:
        clientCredentials:
          authorizationUrl: https://nap-1926.it/auth/nap/token
          scopes:
            read:shapshot: accesso alle API e al download