Difference between revisions of "StorageHub REST API"

From Gcube Wiki
Jump to: navigation, search
(Create Folder)
Line 55: Line 55:
 
200 The workspace root item (in json format) is returned.
 
200 The workspace root item (in json format) is returned.
  
400 The error is specified in the body of the response message
+
500 The error is specified in the body of the response message
  
 
== Get Item ById ==
 
== Get Item ById ==
Line 90: Line 90:
 
200 the list of the Items (in JSON format)
 
200 the list of the Items (in JSON format)
  
400 The error is specified in the body of the response message
+
500 The error is specified in the body of the response message
  
 
== Retrieve VRE Folder ==
 
== Retrieve VRE Folder ==
Line 110: Line 110:
 
200 The VRE folder root item (in json format) is returned.
 
200 The VRE folder root item (in json format) is returned.
  
400 The error is specified in the body of the response message
+
500 The error is specified in the body of the response message
  
 
== Create Folder ==
 
== Create Folder ==
Line 126: Line 126:
 
=== REST API ===
 
=== REST API ===
  
POST /{destiantion-folder-id}/create/FOLDER?gcube-token={user-token} - FormParameters: {String name, String description, boolean hidden}
+
POST /workspace/items/{destiantion-folder-id}/create/FOLDER?gcube-token={user-token} - FormParameters: {String name, String description, boolean hidden}
  
  
Line 133: Line 133:
 
200 The Folder item identifier is returned.
 
200 The Folder item identifier is returned.
  
400 The error is specified in the body of the response message
+
500 The error is specified in the body of the response message
  
 
== Upload File ==
 
== Upload File ==
Line 154: Line 154:
 
=== REST API ===
 
=== REST API ===
  
POST /{destination-folder-id}/create/FILE?gcube-token={user-token} - MultipartFormData: {String name, String description, File file}
+
POST /workspace/items/{destination-folder-id}/create/FILE?gcube-token={user-token} - MultipartFormData: {String name, String description, File file}
 +
 
 +
== GEt Public Url of a File ==
 +
 
 +
Returns the public URL of a file
 +
 
 +
=== Java ===
 +
<source lang="java">
 +
  StorageHubClient shc = new StorageHubClient();
 +
  shc.open({item-id}).asFile().getPublicLink();
 +
 
 +
  //returns the public link for a specific version of the file 
 +
  shc.open({item-id}).asFile().getPublicLink({file-version});
 +
 
 +
</source>
 +
 
 +
=== REST API ===
 +
 
 +
GET /workspace/items/{item-id}/publiclink?gcube-token={user-token}&version={file-version} //version is optional
  
  
 
==== responses ====
 
==== responses ====
  
200 The File item identifier is returned.
+
200 The public URL is returned.
  
400 The error is specified in the body of the response message
+
500 The error is specified in the body of the response message
  
 
== DataMiner and SAI Interactions ==
 
== DataMiner and SAI Interactions ==

Revision as of 15:32, 18 February 2019

Overview

The StorageHub APIs components provide a simple access to StorageHub service.

It is conceived to support both Java and REST-based calls.

Dependencies

Maven coordinates

<dependency>
<groupId>org.gcube.common</groupId>
<artifactId>storagehub-client-library</artifactId>
<version>[1.0.0,2.0.0)</version>
</dependency>

Key features

Users must use the personal token to access the REST interface. They can access just their own files and the folders shared with them.

StorageHub REST interface supports the following operations:

  • Retrieve WS: to retrieve the user Workspace;
  • Folder Listing: to list the content of a folder;
  • Retrieve VRE Folder: to retrieve the VREFolder related to the token;
  • Delete: to remove a file or a folder (including subfolders);
  • Download: to download a file or a folder in ZIP format;
  • Get Public Link: to get a public link of a file;
  • Create Folder: to create a folder in the given parent folder;
  • Unzip: to upload a zip file in a specific folder;
  • Upload file: to upload a file in a folder.

API

Retrieve Workspace

Returns the Item representing the workspace of the user retrieved by the token used for the call.

Java

 StorageHubClient shc = new StorageHubClient();
 FolderContainer rootContianer = shc.getWSRoot()

REST API

GET /workspace/?gcube-token={user-token}

responses

200 The workspace root item (in json format) is returned.

500 The error is specified in the body of the response message

Get Item ById

Java

String theId = {itemIdentifier} // the identifier of the item 
ItemManagerClient client = AbstractPlugin.item().build();
Item theItem = client.get(theId, "hl:accounting");

Folder Listing

Returns the content of a Folder

Java

StorageHubClient shc = new StorageHubClient();
FolderContainer folderContainer = shc.open("{folderIdentifier}").asFolder();
List<? extends Item> items = folderContainer.list().getItems();

REST API

GET /workspace/items/{itemIdentifier}/?gcube-token={userToken}

parameters

{itemIdentifier} the identifier of the item to list the content

responses

200 the list of the Items (in JSON format)

500 The error is specified in the body of the response message

Retrieve VRE Folder

Return the Item representing the root of the VRE folder related to the user token.

Java

 StorageHubClient shc = new StorageHubClient();
 FolderContainer rootContainer = shc.openVREFolder();

REST API

GET /workspace/vrefolder?gcube-token={user-token}

responses

200 The VRE folder root item (in json format) is returned.

500 The error is specified in the body of the response message

Create Folder

Creates a new folder under another folder (specified by its id)

Java

   StorageHubClient shc = new StorageHubClient();
   FolderContainer root = shc.getWSRoot();
   //Creating the folder on the root workspace folder
   root.newFolder("name", "description");

REST API

POST /workspace/items/{destiantion-folder-id}/create/FOLDER?gcube-token={user-token} - FormParameters: {String name, String description, boolean hidden}


responses

200 The Folder item identifier is returned.

500 The error is specified in the body of the response message

Upload File

Creates a new file under a folder (specified by its id)

Java

   StorageHubClient shc = new StorageHubClient();
   FolderContainer root = shc.getWSRoot();
   //Creating the folder on the root workspace folder
   FileContainer file = null;
   try(InputStream is = new FileInputStream(new File("{file-to-upload}"))){
	file = root.uploadFile(is, "name", "description");
   } catch (Exception e) {
	//print the error
   }

REST API

POST /workspace/items/{destination-folder-id}/create/FILE?gcube-token={user-token} - MultipartFormData: {String name, String description, File file}

GEt Public Url of a File

Returns the public URL of a file

Java

   StorageHubClient shc = new StorageHubClient();
   shc.open({item-id}).asFile().getPublicLink();
 
   //returns the public link for a specific version of the file  
   shc.open({item-id}).asFile().getPublicLink({file-version});

REST API

GET /workspace/items/{item-id}/publiclink?gcube-token={user-token}&version={file-version} //version is optional


responses

200 The public URL is returned.

500 The error is specified in the body of the response message

DataMiner and SAI Interactions

Algorithms created in SAI and executed by DataMiner can interact with StorageHub through the StorageHub REST APIs. Here are some examples: