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.1
  
  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: Type
    description: operations for data types
  - name: Data Catalog
    description: operations for data catalogs
  - 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]

  /catalog:
    get:
      summary: Restituisce i Cataloghi disponibili
      tags: [Data Catalog]
      operationId: getCatalogs
      parameters:
        - name: sources
          in: query
          description: Sources to filter by
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Catalog'
    post:
      summary: Crea un nuovo Catalogo Dati (admin only)
      tags: [Data Catalog]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Catalog'
      responses:
        '201':
          description: Catalogo creato

  /catalog/{id}:
    get:
      summary: Restituisce un singolo Catalogo Dati
      tags: [Data Catalog]
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Catalogo trovato
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Catalog'
        '404':
          description: Catalogo non trovato

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

    delete:
      summary: Elimina un catalogo vuoto esistente (admin only)
      tags: [Data Catalog]

  /source:
    get:
      summary: Restituisce le fonti dati disponibili
      tags: [Data Catalog]
      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 Catalog]

  /source/{id}:

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

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

  /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)
        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/'
        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à
        name:
          type: string
          description: Nome canonico del Tipo di Entità
        stateType:
          $ref: '#/components/schemas/Type'
        syntax:
          type: string
          format: json
          description: Definizione (JSON-LD) della sintassi del Tipo di Entità
        terminology:
          $ref: '#/components/schemas/Terminology'

    State:
      type: object
      description: Definisce una possibile rappresentazione della situazione attuale nel «divenire» delle Entità di un certo Tipo
      examples: 
        - ElectronicDeviceState - 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
        kind:
          type: string
          description: La tipologia elementare del Tipo di Stato (grandezza con unità di misura, stringa, eccetera)

    Entity:
      type: object
      description: rappresenta un generico oggetto urbano, è di uno specifico tipo, afferisce a un catalogo, ha uno stato dinamico, è dotato di proprietà type-specific, è tipicamente geo-localizzabile
      required: [id, type, state, createdDate, updatedDate]
      properties:
        id:
          type: string
          format: uri
          description: URI univoco dell’Entità sulla piattaforma
        type:
          $ref: '#/components/schemas/Type'
        parent:
          $ref: '#/components/schemas/Entity'
        externalId:
          type: string
          description: Identificativo dell’Entità nel sistema sorgente
        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
        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
        name:
          type: string
          description: Nome canonico della Fonte Dati
        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
      required: [id, name, organization, internal]

    Catalog:
      type: object
      description: Catalogo Dati (Data Catalog) fornito da una Fonte Dati
      properties:
        id:
          type: string
          format: uri
          description: ID univoco del Catalogo Dati
        name:
          type: string
          description: Nome canonico del Catalogo Dati
        source:
          description: Fonte Dati di afferenza
          $ref: '#/components/schemas/Source'
      required: [id, name, source]

    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