API/panorama.yaml

openapi: 3.1.0
info:
  title: Edison Next Panorama - Integration API
  description: |-
    API standard di integrazione di *Edison Next Panorama* con sistemi esterni
  version: 1.0.0
#servers:
#  - url: https://api.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 to query data catalog and data types
  - name: Entity
    description: operations to manage entities
  - 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'

  /catalog:
    get:
      summary: Restituisce i Cataloghi disponibili
      tags: [Type]
      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'

  /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'

  /entity:
    get:
      summary: Elenco di tutte le entità
      tags: [Entity]
      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]
      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]
      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
      responses:
        '200':
          description: Lista di dispositivi
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
    post:
      summary: Crea un nuovo dispositivo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Device'
      responses:
        '201':
          description: Device creato

  /device/{id}:
    get:
      summary: Ottiene un singolo dispositivo
      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
    put:
      summary: Modifica un dispositivo esistente
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Device'
      responses:
        '200':
          description: Dispositivo aggiornato

    delete:
      summary: Elimina un dispositivo
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Dispositivo eliminato

  /login:
    post:
      summary: Login utente
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Login riuscito
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
        '401':
          description: Credenziali non valide


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
        organization:
          type: string
          description: Organizzazione di riferimento (ovvero soggetto alimentante) per la Fonte Dati
      required: [id, name, organization]

    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