API/panorama.yaml

# yaml-language-server: $schema=https://schemas.sourcemeta.com/openapi/v3.1/schema/2025-09-15.json

openapi: 3.1.0
info:
  title: Edison Next Panorama - Integration API
  description: |-
    API standard di integrazione di *Edison Next Panorama* con sistemi esterni

  contact:
    name: API Support
    email: support@panorama.edisonnext.it

  version: 0.9.2
  
  license:
    name: © 2025 - 2030 Copyright Edison Next Spa. All rights reserved
    url: https://edisonnext.it

externalDocs:
  description: Edison Next Panorama - Specifiche di Integrazione v.1.0
  url: https://panorama.edisonnext.it/ 

# security di default (richiesta anche per accedere ai dati in lettura)
security:
  - panorama_consumer_api_key: []

#servers:
#  - url: https://panorama.edisonnext.it/api/v1
#    description: Main (production) API server
#  - url: <Here staging API server>
#    description: Staging API server
#  - url: <Here development API server>
#    description: Development API server
tags:
  - name: Data Source
    description: operations for data sources
  - name: Type
    description: operations for data types
  - name: Entity Browse
    description: operations to browse entities and their state
  - name: Entity
    description: operations to manage entities (data provider only)
  - name: Device
    description: Operations about Devices
paths:
  /type:
    get:
      summary: Restituisce i Tipi di Entità definiti
      tags: [Type]
      operationId: getTypes
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Type'
    post:
      summary: Crea un nuovo Tipo di Entità (admin only)
      tags: [Type]
#      security:
#        - panorama_administrator_api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Type'
      responses:
        '201':
          description: Tipo creato

  /type/{id}:
    get:
      summary: Restituisce un singolo Tipo di Entità
      tags: [Type]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Tipo trovato
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Type'
        '404':
          description: Tipo non trovato

    put:
      summary: Modifica un Tipo esistente (admin only)
      tags: [Type]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Type'
      responses:
        '200':
          description: Tipo aggiornato

    delete:
      summary: Elimina un Tipo (senza istanze di elementi) esistente (admin only)
      tags: [Type]

  /source:
    get:
      summary: Restituisce le fonti dati disponibili
      tags: [Data Source]
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Source'

    post:
      summary: Aggiunge una Fonte Dati (admin only)
      tags: [Data Source]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Source'
      responses:
        '201':
          description: Fonte Dati creata

  /source/{id}:

    put:
      summary: Modifica una sorgente dati esistente (admin only)
      tags: [Data Source]

    delete:
      summary: Elimina una sorgente dati (vuota) esistente (admin only)
      tags: [Data Source]

  /terminology:
    get:
      summary: Restituisce le Nomenclature definite
      tags: [Type]
      operationId: getTerminologies
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Terminology'
    post:
      summary: Crea una nuova Nomenclatura (admin only)
      tags: [Type]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Terminology'
      responses:
        '201':
          description: Nomenclatura creata

  /terminology/{id}:

    get:
      summary: Restituisce una singola Nomenclatura
      tags: [Type]
    put:
      summary: Modifica una Nomenclatura esistente (admin only)
      tags: [Type]
    delete:
      summary: Elimina una Nomenclatura (senza riferimenti in qualche tipo) esistente (admin only)
      tags: [Type]

  /entity:
    get:
      summary: Ricerca di entità
      tags: [Entity Browse]
      parameters:
        - name: type
          in: query
          description: Filter by entity type
          required: false
          explode: true
          schema:
            type: string
        - name: catalog
          in: query
          description: Filter by data catalog
          required: false
          explode: true
          schema:
            type: string
        - name: state
          in: query
          description: Filter by entity state
          required: false
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: Lista di entità
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Entity'

    post:
      summary: Crea una nuova entità
      tags: [Entity]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Entity'
      responses:
        '201':
          description: Entità creata

  /entity/{id}:
    get:
      summary: Ottiene una singola entità
      tags: [Entity Browse]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Entità trovata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '404':
          description: Entità non trovata

    put:
      summary: Modifica un'entità esistente (escluso lo stato)
      tags: [Entity]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Entity'
      responses:
        '200':
          description: Entità aggiornata

    delete:
      summary: Elimina un'entità
      tags: [Entity]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Entità eliminata

  /state/{id}:
    put:
      summary: Modifica lo stato di un'Entità
      tags: [Entity]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
      responses:
        '200':
          description: Stato Entità aggiornato

  /history/{id}:
    get:
      summary: Ottiene la storia delle variazioni di stato di un'Entità
      tags: [Entity Browse]
      parameters:
        - in: path
          name: id
          description: l'ID dell'entità di cui ottenere la storia
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Entità trovata
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object 
                  properties:
                    timestamp:
                      type: string
                      format: date-time
                    state:
                      type: string
                      examples: ['off', '22°C']
        '404':
          description: Entità non trovata

  /device:
    get:
      summary: Elenco di tutti i dispositivi
      tags: [Device]
      responses:
        '200':
          description: Lista di dispositivi
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'

  /device/{id}:
    get:
      summary: Ottiene informazioni su un singolo dispositivo
      tags: [Device]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dispositivo trovato
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '404':
          description: Dispositivo non trovato

components:
  schemas:
    Terminology:
      type: object
      description: Nomenclatura di riferimento per i Tipi di Entità. Può essere interna o esterna (schema.gov.it, UCUM, Google Knowledge Graph)
      required: [id, name, syntax]
      properties:
        id:
          type: string
          format: uri
          description: Identificativo univoco della Nomenclatura (terminology)
          examples: 
            - http://dati.beniculturali.it/cis
        name:
          type: string
          description: Nome canonico della Nomenclatura
        description:
          type: string
          description: Descrizione della Nomenclatura
        documentation:
          type: string
          format: uri
          description: Link alla documentazione della Nomenclatura
          examples: 
            - 'https://schema.gov.it/'
        subject:
          type: string
          description: Soggetto titolare del Tipo
          examples:
            - 'Ministero per i Beni e le Attività Culturali'
        uri:
          type: string
          format: uri
          description: URI autoritativa della Nomenclatura
          examples: 
            - http://dati.beniculturali.it/cis

    Type:
      type: object
      description: Tipi di entità, comprensivi di riferimento al nomenclatore e definizione della struttura del payload specifico
      required: [id, name, syntax]
      properties:
        id:
          type: string
          format: uri
          description: Identificativo univoco del Tipo di Entità
          examples:
            - http://dati.beniculturali.it/cis/CulturalInstituteOrSite
        name:
          type: string
          description: Nome canonico del Tipo di Entità
          examples:
            - Istituti e Luoghi Della Cultura Italiani (musei, biblioteche, cinema, ecc)
        native:
          type: boolean
          description: Se il Tipo è nativo di piattaforma o importato
          default: false
        stateType:
          $ref: '#/components/schemas/State'
        syntax:
          type: string
          format: json
          description: Definizione (JSON-LD) della sintassi del Tipo di Entità
        terminology:
          $ref: '#/components/schemas/Terminology'
          examples:
            - http://dati.beniculturali.it/cis
        uri:
          type: string
          format: uri
          description: URI autoritativo del Tipo (se non nativo)
          examples: 
            - http://dati.beniculturali.it/cis/CulturalInstituteOrSite

    State:
      type: object
      description: Definisce una possibile rappresentazione della situazione attuale nel «divenire» delle Entità di un certo Tipo
      examples: 
        - Aperto o Chiuso
        - Acceso o Spento
        - (StatoSemaforo) Rosso, Giallo, Verde, Lampeggiante, Spento
        - TemperaturaAmbiente - la temperatura attuale di un ambiente in gradi centigradi
      properties:
        id:
          type: string
          format: uri
          description: ID univoco del Tipo di Stato
        name:
          type: string
          description: Nome canonico del Tipo di Stato
        uom:
          type: string
          description: Unità di misura (per grandezze scalari)
        kind:
          type: string
          description: La tipologia elementare del Tipo di Stato (grandezza con unità di misura, stringa, eccetera)
          examples:
            - Enumeration
            - Number
            - String

    Entity:
      type: object
      description: rappresenta un generico oggetto urbano, è di uno specifico Tipo, afferisce a una Sorgente Dati, ha uno Stato dinamico, è dotato di proprietà type-specific, può avere un Device associato, è tipicamente geo-localizzabile
      required: [id, type, source, createdDate, updatedDate]
      properties:
        id:
          type: string
          description: ID univoco dell'Entità sulla piattaforma
        name:
          type: string
          description: Nome canonico dell'Entità sulla piattaforma
          examples:
            - Antiquarium e Acquedotto romano di Trieste
        geometry:
          type: object
          description: Coordinate geografiche dell'Entità
          properties:
            lat:
              type: Number
              description: Latitudine dell'Entità
              examples: [45.61809]
            long:
              type: Number
              description: Longitudine dell'Entità
              examples: [13.827805]
        type:
          $ref: '#/components/schemas/Type'
        parent:
          $ref: '#/components/schemas/Entity'
        source:
          $ref: '#/components/schemas/Source'
        externalId:
          type: string
          description: Identificativo dell'Entità nel sistema sorgente
          examples:
            - http://dati.beniculturali.it/mibact/luoghi/resource/CISNameInTime/20738
        state:
          type: object
          description: Stato dell'entità
          properties:
            value:
              type: string
              description: Valore dello stato (determinato da Type.stateType)
            timestamp:
              type: string
              format: date-time
              description: Data/ora dello stato
            validity:
              type: object
              properties:
                from:
                  type: string
                  format: date-time
                  description: Inizio validità
                to:
                  type: string
                  format: date-time
                  description: Fine validità
        payload:
          type: object
          description: Attributi personalizzati in base al tipo di entità
          additionalProperties: true
          examples: 
            - { chiusura: 'Lunedì|Giovedì|Domenica' }
        deviceId:
          description: Device associato all'entità
          $ref: '#/components/schemas/Device'
        createdDate:
          type: string
          format: date-time
          description: Data e ora di creazione dell'entità (timestamp ISO 8601)
        updatedDate:
          type: string
          format: date-time
          description: Data e ora dell'ultima modifica all'entità, escluse le modifiche di stato (timestamp ISO 8601)

    Source:
      type: object
      description: Fonte dati, interna o esterna, relativa a un soggetto alimentante
      properties:
        id:
          type: string
          format: uri
          description: ID univoco della Fonte Dati
          examples: 
            - 'fvg_ispfor_tsgo'
            - 'fvg_ispfor'
        name:
          type: string
          description: Nome canonico della Fonte Dati
          examples:
            - 'Ministero per i Beni e le Attività Culturali'
            - 'Vincolo idrogeologico. L. 3267/1923 Comune di Trieste'
            - 'Ispettorati forestali'
            - 'Recupero energetico di biogas da digestione anaerobica o da discarica R1 (BDAD)'
            - 'Area golenale'
            - 'Copertura 2019 della banda larga in Italia secondo i criteri di rilevazione DESI 2020'
        internal:
          type: boolean
          description: Indica se la fonte dati è nativa della piattaforma o meno
          default: false
        organization:
          type: string
          description: Organizzazione di riferimento (ovvero soggetto alimentante) per la Fonte Dati
          examples:
            - 'Ministero per i Beni e le Attività Culturali'
            - 'Regione Autonoma Friuli Venezia Giulia - ISPETTORATO FORESTALE DI TRIESTE E GORIZIA'
            - 'RAFVG - DC Risorse agroalimentari, forestali e ittiche - Area foreste e territorio'
            - 'Regione Autonoma Friuli Venezia Giulia - SERVIZIO DISCIPLINA GESTIONE RIFIUTI E SITI INQUINATI'
            - 'Regione Autonoma Friuli Venezia Giulia - SERVIZIO GEOLOGICO'
            - 'Autorità per le Garanzie nelle Comunicazioni - AGCOM'
        processor:
          type: string
          description: Organizzazione che gestisce tecnicamente la Fonte Dati
          examples: 
            - 'Insiel S.p.A.'
            - 'Regione autonoma Friuli Venezia Giulia'
      required: [id, name, organization, internal]

    Device:
      type: object
      description: Dispositivo IoT gestito nativamente in piattaforma
      required: [id, fk_firmware_id, fk_tenant_code, fk_device_service_id, created_date, updated_date]
      properties:
        id:
          type: string
          format: uri
          description: Identificativo univoco del dispositivo
        serial:
          type: string
          description: Seriale del dispositivo
        fk_firmware_id:
          type: string
          format: uri
          description: Identificativo univoco del firmware del dispositivo   
        fk_tenant_code:
          type: string
          format: uri
          description: Identificativo univoco del tenant appartenente il dispositivo
        fk_device_service_id:
          type: string
          format: uri
          description: Identificativo univoco del servizio          
        decrypt_key:
          type: string
          description: Chiave di decrypting del dispositivo
        auth_key:
          type: string
          description: Chiave di authentication del dispositivo 
        logical_device_name:
          type: string
          description: Logical device name del dispositivo     
        mac_address:
          type: string
          description: Mac address del dispositivo          
        createdDate:
          type: string
          format: date-time
          description: Data di creazione
        updatedDate:
          type: string
          format: date-time
          description: Ultimo aggiornamento      

  securitySchemes:
    panorama_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://panorama.edisonnext.it/oauth/authorize
          scopes:
            "write:entities": Panorama data provider
            "read:entities": Panorama data consumer
            "write:types": Panorama tenant administrator
    panorama_consumer_api_key:
      type: apiKey
      name: consumerApiKey
      in: header
    panorama_provider_api_key:
      type: apiKey
      name: providerApiKey
      in: header
    panorama_administrator_api_key:
      type: apiKey
      name: administratorApiKey
      in: header