completato enumerazione operazioni

panorama.yaml

@@ -1,11 +1,31 @@
+# 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
-  version: 1.0.0
+
+  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://api.panorama.edisonnext.it/api/v1
+#  - url: https://panorama.edisonnext.it/api/v1
 #    description: Main (production) API server
 #  - url: <Here staging API server>
 #    description: Staging API server
@@ -13,9 +33,13 @@ info:
 #    description: Development API server
 tags:
   - name: Type
-    description: operations to query data catalog and data types
+    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
+    description: operations to manage entities (data provider only)
   - name: Device
     description: Operations about Devices
 paths:
@@ -33,11 +57,68 @@ paths:
                 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: [Type]
+      tags: [Data Catalog]
       operationId: getCatalogs
       parameters:
         - name: sources
@@ -49,7 +130,6 @@ paths:
             type: array
             items:
               type: string
-
       responses:
         '200':
           description: successful operation
@@ -59,6 +139,89 @@ paths:
                 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:
@@ -74,11 +237,57 @@ paths:
                 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: Elenco di tutte le entità
-      tags: [Entity]
+      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à
@@ -105,7 +314,7 @@ paths:
   /entity/{id}:
     get:
       summary: Ottiene una singola entità
-      tags: [Entity]
+      tags: [Entity Browse]
       parameters:
         - in: path
           name: id
@@ -177,7 +386,7 @@ paths:
   /history/{id}:
     get:
       summary: Ottiene la storia delle variazioni di stato di un'Entità
-      tags: [Entity]
+      tags: [Entity Browse]
       parameters:
         - in: path
           name: id
@@ -207,6 +416,7 @@ paths:
   /device:
     get:
       summary: Elenco di tutti i dispositivi
+      tags: [Device]
       responses:
         '200':
           description: Lista di dispositivi
@@ -216,21 +426,11 @@ paths:
                 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
+      summary: Ottiene informazioni su un singolo dispositivo
+      tags: [Device]
       parameters:
         - in: path
           name: id
@@ -246,64 +446,6 @@ paths:
                 $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:
@@ -440,10 +582,14 @@ components:
         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]
+      required: [id, name, organization, internal]
 
     Catalog:
       type: object
@@ -505,3 +651,26 @@ components:
           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