rapipdf

{ "openapi": "3.0.2", "info": { "title": "gCloud Storage", "version": "1.0.0", "description": "Questo documento rappresenta la guida operativa di riferimento per lo sviluppo di componenti software che interagiscono con l'infrastruttura gCloud Storage. Il target di questa documentazione si intende, quindi, di tipo tecnico; nello specifico il documento è indirizzato ai programmatori che si trovano a dover interagire con gCloud Storage per memorizzare documenti al suo interno.\n\ngCloud Storage è un servizio di memorizzazione di documenti. Nell'ottica dei servizi di tipo Storage-as-a-Service permette a qualsiasi applicazione di memorizzare documenti gestendo con maggiore semplicità le problematiche legate alla scalabilità del proprio servizio, al salvataggio e conservazione in locazioni multiple dei documenti, alla gestione del versioning dei documenti gestiti, ed alla problematiche di backup in maniera semplice e trasparente per l'applicazione stessa.\nI servizi di gCloud Storage sono erogati tramite dei web-services, previa autenticazione tramite una chiave univoca e specifica di ogni applicazione che usufruisca delle funzionalità di gCloud Storage.\n\nModalità di interfacciamento:\nI web services alla base dei servizi di gCloud Storage sono basati su un approccio di tipo REST. Operativamente questo vuol dire che essi sono tutti operanti in una logica stateless che non utilizza sessioni o cookie, cachable che può trarre vantaggio dalla disponibilità di proxy o load-accelerator lungo il percorso tra il server gCloud Storage e l'applicazione che ne sfrutti i servizi, sviluppati in un'ottica client-server suddivisa in livelli di interfaccia diverse.\nOgni oggetto gestito da gCloud Storage viene quindi codificato in maniera tale da poter essere rappresentato tramite un indirizzo che lo identifichi univocamente in una maniera gerarchica tale da ricalcare la natura dell'informazione che rappresenta.\nPer ognuna di queste rappresentazioni univoche di un oggetto o di una sua concettualizzazione, è possibile interagire tramite dei metodi standard predefiniti (GET, POST, PUT, PATCH e DELETE) propri del protocollo HTTP su cui è basata l'implementazione REST di gCloud Storage.\ngCloud Storage opera sia tramite il protocollo HTTP standard che tramite il più sicuro protocollo HTTPS.", "contact": { "name": "Schema31 SPA", "url": "https://www.schema31.it/", "email": "gcloud@schema31.it" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" } }, "servers": [ { "url": "https://storage.gcloud.schema31.it/api", "description": "Server di Produzione del sistema gCloud Storage." } ], "paths": { "/repository": { "summary": "End-point associato alle iterazioni con i Repository di gCloud Storage", "description": "Tramite questo end point è possibile interagire con i Repository che sono stati definiti nel pannello di amministrazione di gCloud Storage.\n\nL'unico metodo esposto è il metodo in GET che permette all'utente di avere, in tempo reale, informazioni sulla numerosità e sulle dimensioni dei documenti contenuti all'interno del Repository documentale.", "get": { "tags": [ "Repository" ], "responses": { "200": { "content": { "application/json": { "schema": { "required": [ "totalfiles", "totalsize", "uniquefiles", "uniquesize", "maxQuota" ], "type": "object", "properties": { "totalfiles": { "description": "indica il numero complessivo di files all'interno del repository", "type": "integer" }, "totalsize": { "description": "indica lo spazio complessivamente occupato dai files del repository", "type": "integer" }, "uniquefiles": { "description": "indica il numero complessivo di files univoci all'interno del repository", "type": "integer" }, "uniquesize": { "description": "indica lo spazio complessivamente occupato dai files univoci del repository", "type": "integer" }, "maxQuota": { "description": "indica la dimensione massima occupabile dal repository (-1 se illimitata)", "type": "integer" } } }, "examples": { "Repository con limiti": { "value": { "totalfiles": 1, "totalsize": 445, "uniquefiles": 1, "uniquesize": 445, "maxQuota": 5000000000 } }, "Repository illimitato": { "value": { "totalfiles": 3, "totalsize": 424, "uniquefiles": 3, "uniquesize": 424, "maxQuota": -1 } } } } }, "description": "Richiesta gestita con successo" }, "403": { "$ref": "#/components/responses/AuthenticationFailed" }, "404": { "$ref": "#/components/responses/Repository_NotFound" } }, "security": [ { "APIKey": [] } ], "operationId": "getRepositoryById", "summary": "Dettagli repository", "description": "Metodo per recuperare la lista dei file contenuti in un repository" }, "parameters": [ { "examples": { "Documentation repository": { "value": "ApiaryDoc" } }, "name": "repositoryName", "description": "nome del repository con cui si sta interagendo", "schema": { "type": "string" }, "in": "header", "required": true } ] }, "/resource": { "description": "L’entità di tipo resource rappresenta la singola risorsa memorizzata all’interno del sistema gCloud Storage.\n\nOgni resource è associata ad un singolo repository ed è caratterizzata da una fileKey e da una fileVersion; l'accoppiata di queste due proprietà identifica univocamente un file ed è alla base del meccanismo di versionamento interno a gCloud Storage.\n\nQuesto meccanismo si basa sul concetto che ad ogni fileKey possono essere associate molteplici fileVersion; a parità di fileKey, la resource con valore di fileVersion più alto indica la versione più recente del file.\n\nNel recuperare una resource, è possibile omettere l'indicazione della fileVersion per referenziare sempre la versione più recente del file.", "post": { "requestBody": { "description": "Rappresentazione multipart del documento da caricare sul repository", "content": { "multipart/form-data": { "schema": { "properties": { "file": { "type": "array", "items": { "format": "binary", "type": "string" } } } } } }, "required": true }, "tags": [ "Resource" ], "responses": { "201": { "content": { "application/json": { "schema": { "required": [ "fileKey", "fileVersion", "Status" ], "type": "object", "properties": { "fileKey": { "description": "chiave univoca identificativa del file", "type": "string" }, "fileVersion": { "description": "versione assegnata al nuovo file", "type": "integer" }, "Status": { "description": "esito dell'operazione", "type": "string" }, "fileIdentifier": { "description": "identificativo interno del file", "type": "string" } } }, "examples": { "Esempio di salvataggio": { "value": { "Result": [ { "fileKey": "7bf2a632-2f2e-480f-a892-af504121826a", "fileVersion": 2, "fileIdentifier": "XXXXXXXXX3bd14f1", "Status": "OK" } ] } } } } }, "description": "Resource creata correttamente" } }, "operationId": "createResource", "summary": "Crea nuova risorsa", "description": "Tramite questo endpoint è possibile creare un nuovo documento all'interno di un repository" }, "parameters": [ { "name": "repositoryName", "description": "nome del repository", "schema": { "type": "string" }, "in": "header", "required": true } ] }, "/resource/fileKey/{fileKey}": { "summary": "Accede alle risorse", "description": "Sottoparte delle api che raccoglie le funzionalità di interazione con le risorse", "get": { "tags": [ "Resource" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } }, "description": "Risorsa trovata" }, "403": { "$ref": "#/components/responses/AuthenticationFailed" }, "404": { "$ref": "#/components/responses/Resource_NotFound" } }, "security": [ { "APIKey": [] } ], "operationId": "getResourceByFilekey", "summary": "Dettagli documento", "description": "Operazione per recuperare i metadati di una documento presente nel sistema. Non essendo specificata la versione del documento da recuperare, il sistema ritornerà sempre il dettaglio della versione più recente del documento presente a sistema." }, "post": { "requestBody": { "description": "Rappresentazione multipart del documento da caricare sul repository", "content": { "multipart/form-data": { "schema": { "properties": { "file": { "type": "array", "items": { "format": "binary", "type": "string" } } } } } }, "required": true }, "tags": [ "Resource" ], "responses": { "201": { "content": { "application/json": { "schema": { "required": [ "fileKey", "fileVersion", "Status" ], "type": "object", "properties": { "fileKey": { "description": "chiave univoca identificativa del file", "type": "string" }, "fileVersion": { "description": "versione assegnata al nuovo file", "type": "integer" }, "Status": { "description": "esito dell'operazione", "type": "string" }, "fileIdentifier": { "description": "identificativo interno del file", "type": "string" } } }, "examples": { "Esempio di salvataggio": { "value": { "Result": [ { "fileKey": "7bf2a632-2f2e-480f-a892-af504121826a", "fileVersion": 2, "fileIdentifier": "XXXXXXXXX3bd14f1", "Status": "OK" } ] } } } } }, "description": "Resource creata correttamente" } }, "operationId": "updateResource", "summary": "Sostituisce documento", "description": "Tramite questo endpoint è possibile creare una nuova versione di un documento" }, "delete": { "tags": [ "Resource" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" }, "examples": { "DeletedResource": { "value": { "isDeleted": "1", "fileKey": "7bf2a632-2f2e-480f-a892-af504121826a", "fileVersion": "2", "fileSize": "445", "fileMD5": "db89bb5ceab87f9c0fcc2ab36c189c2c", "fileSHA256": "2d8c2f6d978ca21712b5f6de36c9d31fa8e96a4fa5d8ff8b0188dfb9e7c171bb", "fileName": "LoremIpsum.txt", "fileMimeType": "text/plain", "fsFileId": "41072853", "creationTime": "2015-10-28 14:26:56", "Repository": "ApiaryDoc", "publicRepository": "0", "friendlyUrl": "https://storage.gcloud.schema31.it/obj/7bf2a632-2f2e-480f-a892-af504121826a/2", "resourceIdentifier": "XXXXXXXXX3bd14f1" } } } } }, "description": "Cancellazione avvenuta con successo." }, "403": { "$ref": "#/components/responses/AuthenticationFailed" }, "404": { "$ref": "#/components/responses/Resource_NotFound" } }, "security": [ { "APIKey": [] } ], "operationId": "deleteResourceByFilekey", "summary": "Cancella documento", "description": "Metodo per cancellare un documento dal sistema. Non essendo specificata la versione del documento da cancellare, il sistema cancellerà la versione più recente, non cancellata, del documento presente a sistema." }, "patch": { "tags": [ "Resource" ], "parameters": [ { "name": "undeleteFile", "description": "Header per richiedere il ripristino di un file cancellato", "schema": { "type": "boolean" }, "in": "header" }, { "name": "editFileName", "description": "Controlla se modificare il nome di un documento", "schema": { "type": "boolean" }, "in": "header" }, { "name": "fileName", "description": "Nuovo nome file se editFileName è true", "schema": { "type": "string" }, "in": "header" }, { "name": "editFileMimeType", "description": "Controlla se modificare il mime-type di un documento", "schema": { "type": "boolean" }, "in": "header" }, { "name": "fileMimeType", "description": "Nuovo mime-type del documento se editFileMimeType è true", "schema": { "type": "string" }, "in": "header" } ], "responses": { "204": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "Default": { "value": [ "some text", "some text" ] } } } }, "description": "Aggiornamento completato" }, "403": { "$ref": "#/components/responses/AuthenticationFailed" }, "404": { "$ref": "#/components/responses/Resource_NotFound" }, "500": { "content": { "application/json": {} }, "description": "Impossibile modificare il dato documento" } }, "operationId": "patchResourceByFileKey", "summary": "Modifica documento", "description": "Metodo per modificare un documento presente a sistema. Non essendo specificata la versione del documento da modificare, il sistema modificherà i dettagli della versione più recente, non cancellata, del documento presente a sistema." }, "parameters": [ { "examples": { "UUID Di Esempio": { "value": "34a49f5c-2977-11e9-8faf-00a0983d30e5" } }, "name": "fileKey", "description": "fileKey da recuperare", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "repositoryName", "description": "nome del repository", "schema": { "type": "string" }, "in": "header", "required": true } ] }, "/resource/fileKey/{fileKey}/fileVersion/{fileVersion}": { "summary": "Accede alle risorse", "description": "Sottoparte delle api che raccoglie le funzionalità di interazione con le risorse", "get": { "tags": [ "Resource" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } }, "description": "Risorsa trovata" }, "403": { "$ref": "#/components/responses/AuthenticationFailed" }, "404": { "$ref": "#/components/responses/Resource_NotFound" } }, "security": [ { "APIKey": [] } ], "operationId": "getResourceByFilekeyFileVersion", "summary": "Dettagli versione documento", "description": "Operazione per recuperare i metadati di una versione specifica di una risorsa nell sistema." }, "delete": { "tags": [ "Resource" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" }, "examples": { "DeletedResource": { "value": { "isDeleted": "1", "fileKey": "7bf2a632-2f2e-480f-a892-af504121826a", "fileVersion": "2", "fileSize": "445", "fileMD5": "db89bb5ceab87f9c0fcc2ab36c189c2c", "fileSHA256": "2d8c2f6d978ca21712b5f6de36c9d31fa8e96a4fa5d8ff8b0188dfb9e7c171bb", "fileName": "LoremIpsum.txt", "fileMimeType": "text/plain", "fsFileId": "41072853", "creationTime": "2015-10-28 14:26:56", "Repository": "ApiaryDoc", "publicRepository": "0", "friendlyUrl": "https://storage.gcloud.schema31.it/obj/7bf2a632-2f2e-480f-a892-af504121826a/2", "resourceIdentifier": "XXXXXXXXX3bd14f1" } } } } }, "description": "Cancellazione avvenuta con successo." }, "403": { "$ref": "#/components/responses/AuthenticationFailed" }, "404": { "$ref": "#/components/responses/Resource_NotFound" } }, "security": [ { "APIKey": [] } ], "operationId": "deleteResourceByFilekeyFileVersion", "summary": "Cancella versione documento", "description": "Metodo per cancellare una versione specifica di un documento presente a sistema." }, "patch": { "tags": [ "Resource" ], "parameters": [ { "name": "undeleteFile", "description": "Header per richiedere il ripristino di un file cancellato", "schema": { "type": "boolean" }, "in": "header" }, { "name": "editFileName", "description": "Controlla se modificare il nome di un documento", "schema": { "type": "boolean" }, "in": "header" }, { "name": "fileName", "description": "Nuovo nome file se editFileName è true", "schema": { "type": "string" }, "in": "header" }, { "name": "editFileMimeType", "description": "Controlla se modificare il mime-type di un documento", "schema": { "type": "boolean" }, "in": "header" }, { "name": "fileMimeType", "description": "Nuovo mime-type del documento se editFileMimeType è true", "schema": { "type": "string" }, "in": "header" } ], "responses": { "204": { "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "Default": { "value": [ "some text", "some text" ] } } } }, "description": "Aggiornamento completato" }, "403": { "$ref": "#/components/responses/AuthenticationFailed" }, "404": { "$ref": "#/components/responses/Resource_NotFound" }, "500": { "content": { "application/json": {} }, "description": "Impossibile modificare il dato documento" } }, "operationId": "patchResourceByFileKeyFileVersion", "summary": "Modifica versione documento", "description": "Metodo per modificare gli attributi di una versione specifica di un documento presente a sistema." }, "parameters": [ { "examples": { "UUID Di Esempio": { "value": "34a49f5c-2977-11e9-8faf-00a0983d30e5" } }, "name": "fileKey", "description": "fileKey da recuperare", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "repositoryName", "description": "nome del repository", "schema": { "type": "string" }, "in": "header", "required": true }, { "examples": { "Default": { "value": "1" } }, "name": "fileVersion", "description": "Versione del documento da recuperare", "schema": { "type": "integer" }, "in": "path", "required": true } ] }, "/resource/fileKey/{fileKey}/fileVersion/{fileVersion}/chain/{chain}/chainFileIndex/{chainFileIndex}": { "summary": "Accede alle risorse", "description": "Sottoparte delle api che raccoglie le funzionalità di interazione con le risorse", "get": { "tags": [ "Resource" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } }, "description": "Risorsa trovata" }, "403": { "$ref": "#/components/responses/AuthenticationFailed" }, "404": { "$ref": "#/components/responses/Resource_NotFound" } }, "security": [ { "APIKey": [] } ], "operationId": "getResourceByFilekeyFileVersionChain", "summary": "Dettagli documento chain", "description": "Operazione per recuperare i metadati di una versione specifica di una risorsa nell sistema." }, "parameters": [ { "examples": { "UUID Di Esempio": { "value": "34a49f5c-2977-11e9-8faf-00a0983d30e5" } }, "name": "fileKey", "description": "fileKey da recuperare", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "repositoryName", "description": "nome del repository", "schema": { "type": "string" }, "in": "header", "required": true }, { "examples": { "Default": { "value": "1" }, "Latest": { "value": "_" } }, "name": "fileVersion", "description": "Versione specifica del documento da recuperare, alternativametne è possibile utilizzare il carattere magico _ per indicare \"l'ultima versione disponibile\".", "schema": { "type": "string" }, "in": "path", "required": true }, { "examples": { "ZIPChain": { "value": "zip" } }, "name": "chain", "description": "nome della chain di plugin che ha generato la risorsa", "schema": { "type": "string" }, "in": "path", "required": true }, { "examples": { "Base": { "value": "0" } }, "name": "chainFileIndex", "description": "indice del file in output generato dalla chain", "schema": { "type": "integer" }, "in": "path", "required": true } ] }, "/resources": { "description": "L’entità di tipo resource rappresenta la singola risorsa memorizzata all’interno del sistema gCloud Storage.\n\nOgni resource è associata ad un singolo repository ed è caratterizzata da una fileKey e da una fileVersion; l'accoppiata di queste due proprietà identifica univocamente un file ed è alla base del meccanismo di versionamento interno a gCloud Storage.\n\nQuesto meccanismo si basa sul concetto che ad ogni fileKey possono essere associate molteplici fileVersion; a parità di fileKey, la resource con valore di fileVersion più alto indica la versione più recente del file.\n\nNel recuperare una resource, è possibile omettere l'indicazione della fileVersion per referenziare sempre la versione più recente del file.", "get": { "tags": [ "Resource", "Repository" ], "parameters": [ { "name": "getVersions", "description": "riporta solo l'ultima versione per ogni fileKey o anche quelle precedenti", "schema": { "enum": [ "0", "1" ], "type": "string" }, "in": "header", "required": false }, { "name": "sortBy", "description": "campo rispetto al quale, i risultati devono essere ordinati", "schema": { "enum": [ "fileKeyAsc", "fileKeyDesc", "dateAsc", "dateDesc", "fileSizeAsc", "fileSizeDesc", "fileNameAsc", "fileNameDesc" ], "type": "string" }, "in": "header" }, { "name": "limit", "description": "numero massimo di risorse da ritornare", "schema": { "type": "integer" }, "in": "header" }, { "name": "offset", "description": "indica da quale risorsa cominciare ad estrapolare le informazioni ritornate", "schema": { "type": "integer" }, "in": "header" }, { "name": "isDeleted", "description": "Elena i file cancellati o non cancellati", "schema": { "enum": [ "0", "1" ], "type": "string" }, "in": "header" }, { "name": "searchTarget", "description": "specifica su quale campo effettuare una ricerca mirata", "schema": { "enum": [ "fileName", "fileKey" ], "type": "string" }, "in": "header" }, { "name": "fileName", "description": "stringa di ricerca", "schema": { "type": "string" }, "in": "header" } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "isDeleted", "fileKey", "fileVersion", "fileSize", "fileMD5", "fileSHA256", "fileName", "fileMimeType", "creationTime", "updateTime", "friendlyUrl", "linkUrl" ], "type": "object", "properties": { "isDeleted": { "description": "booleano che indica eventuale cancellazione della risorsa cercata", "type": "boolean" }, "fileKey": { "description": "chiave univoca identificativa del file", "type": "string" }, "fileVersion": { "description": "versione di riferimento del file", "type": "integer" }, "fileSize": { "description": "dimensione del documento", "type": "integer" }, "fileMD5": { "description": "MD5 del documento", "type": "string" }, "fileSHA256": { "description": "SHA256 del documento", "type": "string" }, "fileName": { "description": "nome del documento", "type": "string" }, "fileMimeType": { "description": "mime type del documento", "type": "string" }, "creationTime": { "description": "data di creazione del documento", "type": "string" }, "updateTime": { "description": "data di ultima modifica del documento", "type": "string" }, "friendlyUrl": { "description": "link per il recupero del contenuto blob del file", "type": "string" }, "linkUrl": { "description": "link per il download del documento", "type": "string" } } } }, "examples": { "Esempio di elenco file": { "value": { "Result": [ { "isDeleted": 0, "fileKey": "7bf2a632-2f2e-480f-a892-af504121826a", "fileVersion": 1, "fileSize": 445, "fileMD5": "db89bb5ceab87f9c0fcc2ab36c189c2c", "fileSHA256": "2d8c2f6d978ca21712b5f6de36c9d31fa8e96a4fa5d8ff8b0188dfb9e7c171bb", "fileName": "LoremIpsum.txt", "fileMimeType": "text/plain", "creationTime": "2015-10-28 14:13:56", "updateTime": "2015-10-28 14:13:56", "friendlyUrl": "https://storage.gcloud.schema31.it/obj/7bf2a632-2f2e-480f-a892-af504121826a", "linkUrl": "https://storage.gcloud.schema31.it/dispatch/7bf2a632-2f2e-480f-a892-af504121826a" } ] } } } } }, "description": "Array di oggetti contenenti i dettagli dei file contenuti nel repository" }, "403": { "$ref": "#/components/responses/AuthenticationFailed" }, "404": { "$ref": "#/components/responses/Repository_NotFound" } }, "security": [ { "APIKey": [] } ], "operationId": "getResourcesByRepository", "summary": "Elenco delle risorse in un repository", "description": "Tramite questo end point è possibile recuperare l'elenco delle risorse presenti all'interno di un repository" }, "parameters": [ { "name": "repositoryName", "description": "nome del repository", "schema": { "type": "string" }, "in": "header", "required": true } ] }, "/shorturl": { "summary": "Entry point che permette di gestire gli Short URL", "post": { "tags": [ "Short URL" ], "parameters": [ { "name": "fileKey", "description": "identificativo univoco del file originale", "schema": { "type": "string" }, "in": "header", "required": true }, { "name": "fileVersion", "description": "Versione del file originale", "schema": { "type": "integer" }, "in": "header" }, { "name": "expiresAt", "description": "Scadenza automatica (in secondi) per lo Short URL", "schema": { "type": "integer" }, "in": "header" }, { "name": "whitelist", "description": "White-List degli indirizzi IP che possono accedere allo Short URL", "schema": { "type": "string" }, "in": "header" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortUrl"