first commit

panorama.yaml

@@ -0,0 +1,507 @@
+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