Difference between revisions of "Home Library REST API"

From Gcube Wiki
Jump to: navigation, search
(→‎List)
(→‎Upload File)
Line 98: Line 98:
 
To upload a file, if it does not already exist:
 
To upload a file, if it does not already exist:
 
<source lang="java">
 
<source lang="java">
−
HL_webapp/rest/Upload?name=$name&description=$description&parentPath=$path
+
HL_WEBAPP/rest/Upload?name=$name&description=$description&parentPath=$path
 
</source>
 
</source>
  
Line 108: Line 108:
 
If you want to skip mimetype and size detect steps because you already know them, you can pass them as parameter:
 
If you want to skip mimetype and size detect steps because you already know them, you can pass them as parameter:
 
<source lang="java">
 
<source lang="java">
−
HL_webapp/rest/Upload?name=$name&description=$description&parentPath=$path&mimetype=$mimetype&size=$size
+
HL_WEBAPP/rest/Upload?name=$name&description=$description&parentPath=$path&mimetype=$mimetype&size=$size
 
</source>
 
</source>
  
 
You have to attach the file as mutipart content of your request.
 
You have to attach the file as mutipart content of your request.
 +
 +
Example:
 +
<source lang="java">
 +
import java.io.BufferedReader;
 +
import java.io.File;
 +
import java.io.InputStreamReader;
 +
import java.io.OutputStream;
 +
import java.net.HttpURLConnection;
 +
import java.net.URL;
 +
import java.net.URLEncoder;
 +
import java.nio.file.Files;
 +
import java.util.UUID;
 +
 +
import org.gcube.common.authorization.library.provider.SecurityTokenProvider;
 +
import com.thoughtworks.xstream.XStream;
 +
 +
public class UploadFileRest {
 +
 +
private static final String DEFAULT_IMAGE = "default.jpg";
 +
private static final String ROOT_PATH = "/Home/valentina.marioli/Workspace/";
 +
 +
public static void main(String[] args) throws Exception {
 +
 +
SecurityTokenProvider.instance.set("***************************");
 +
URL imageURL = UploadFileRest.class.getClassLoader().getResource(DEFAULT_IMAGE);
 +
File file = new File(imageURL.getFile());
 +
 +
byte[] image = Files.readAllBytes(file.toPath());
 +
uploadFile(image, "default-"+ UUID.randomUUID().toString()+".jpg", "my description", ROOT_PATH);
 +
 +
}
 +
 +
 +
public static String uploadFile(byte[] in, String name, String description, String parentPath) throws Exception {
 +
XStream xstream = new XStream();
 +
String uri = HL_WEBAPP + "/rest/Upload?" + "name=" + name+ "&description=" + URLEncoder.encode(description, "UTF-8") + "&parentPath=" + URLEncoder.encode(parentPath, "UTF-8");
 +
 +
URL url = new URL(uri);
 +
HttpURLConnection connection = (HttpURLConnection)url.openConnection();
 +
connection.setDoInput(true);
 +
connection.setDoOutput(true);
 +
connection.setUseCaches(false);
 +
connection.setRequestProperty("Content-Type", "image/jpeg");
 +
connection.setRequestMethod("POST");
 +
TokenUtility.setHeader(connection);
 +
 +
// Write file to response.
 +
    OutputStream output = connection.getOutputStream();
 +
    output.write(in);
 +
    output.close();
 +
   
 +
BufferedReader r = new BufferedReader(new  InputStreamReader(connection.getInputStream()));
 +
 +
StringBuffer response = new StringBuffer();
 +
String inputLine;
 +
while ((inputLine = r.readLine()) != null) {
 +
response.append(inputLine);
 +
}
 +
 +
String xmlOut = response.toString();
 +
return (String) xstream.fromXML(xmlOut);
 +
}
 +
 +
}
 +
 +
</source>
  
 
=== Delete File or folder ===
 
=== Delete File or folder ===

Revision as of 17:26, 26 October 2016

Overview

The Home Library REST interface provides a simple access to basic HL features.

Key features

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

Home Library REST interface supports the following operations:

  • Create Folder: to create a folder in the given parent path;
  • List: to list the content of a folder;
  • Upload file: to upload a file in a folder;
  • Remove files and folders: to remove a file or a folder (including subfolders).

Use cases

Users can:

  • use the browser to call API Methods, using username and his/her token as password;
  • implement a Client in different languages, setting the token on the header of the request.

Design

Architecture

API

Get started

Home Library REST is available from gCube 4.1.

Create Folder

To create a new folder: 

HL_webapp/rest/CreateFolder?name=$name&description=$desc&parentPath=$path

Where:

  • name: the name of the new folder.
  • description: the description for the new folder.
  • parentPath: the position where you want to save the folder.

Example: 

HL_webapp/rest/CreateFolder?name=myFolder&description=myDescription&parentPath=/Home/valentina.marioli/Workspace/MyDocs/

List

To list the content of a folder: 

HL_webapp/rest/List?absPath=$path

Where:

  • absPath: the absolute path of the folder to list.

Example: 

HL_webapp/rest/List?absPath=/Home/valentina.marioli/Workspace/MySpecialFolders/gcube-devNext-NextNext/

Output: A list of entries with:

  • name: the name of the file/folder;
  • flag: true if the item is a folder, false if it is a file.


<map>
  <entry>
    <string>BlueBRIDGE_QER_M13-15_Q5_Template(2).xlsx</string>
    <boolean>false</boolean>
  </entry>
  <entry>
    <string>myFolder</string>
    <boolean>true</boolean>
  </entry>
  <entry>
    <string>home-library-jcr-2.5.0-SNAPSHOT.jar</string>
    <boolean>false</boolean>
  </entry>
  <entry>
    <string>aaa</string>
    <boolean>true</boolean>
  </entry>
  <entry>
    <string>BlueBRIDGE_QER_M13-15_Q5_Template.xlsx</string>
    <boolean>false</boolean>
  </entry>
  <entry>
    <string>BlueBRIDGE_QER_M13-15_Q5_Template(1).xlsx</string>
    <boolean>false</boolean>
  </entry>
</map>

Upload File

To upload a file, if it does not already exist: 

HL_WEBAPP/rest/Upload?name=$name&description=$description&parentPath=$path

Where:

  • name: the file to upload
  • description: a description for the file
  • parentPath: the position where you want to save the file.

If you want to skip mimetype and size detect steps because you already know them, you can pass them as parameter: 

HL_WEBAPP/rest/Upload?name=$name&description=$description&parentPath=$path&mimetype=$mimetype&size=$size

You have to attach the file as mutipart content of your request.

Example: 

import java.io.BufferedReader;
import java.io.File;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.nio.file.Files;
import java.util.UUID;
 
import org.gcube.common.authorization.library.provider.SecurityTokenProvider;
import com.thoughtworks.xstream.XStream;
 
public class UploadFileRest {
 
	private static final String DEFAULT_IMAGE = "default.jpg";
	private static final String ROOT_PATH = "/Home/valentina.marioli/Workspace/";
 
	public static void main(String[] args) throws Exception {
 
		SecurityTokenProvider.instance.set("***************************");
		URL imageURL = UploadFileRest.class.getClassLoader().getResource(DEFAULT_IMAGE);
		File file = new File(imageURL.getFile());
 
		byte[] image = Files.readAllBytes(file.toPath());
		uploadFile(image, "default-"+ UUID.randomUUID().toString()+".jpg", "my description", ROOT_PATH);
 
	}
 
 
	public static String uploadFile(byte[] in, String name, String description, String parentPath) throws Exception {
		XStream xstream = new XStream();
		String uri = HL_WEBAPP + "/rest/Upload?" + "name=" + name+ "&description=" + URLEncoder.encode(description, "UTF-8") + "&parentPath=" + URLEncoder.encode(parentPath, "UTF-8");
 
		URL url = new URL(uri);
		HttpURLConnection connection = (HttpURLConnection)url.openConnection();
		connection.setDoInput(true);
		connection.setDoOutput(true);
		connection.setUseCaches(false);
		connection.setRequestProperty("Content-Type", "image/jpeg");
		connection.setRequestMethod("POST");
		TokenUtility.setHeader(connection);
 
		// Write file to response.
	    OutputStream output = connection.getOutputStream();
	    output.write(in);
	    output.close();
 
		BufferedReader r = new BufferedReader(new  InputStreamReader(connection.getInputStream()));
 
		StringBuffer response = new StringBuffer();
		String inputLine;
		while ((inputLine = r.readLine()) != null) {
			response.append(inputLine);
		}
 
		String xmlOut = response.toString();
		return (String) xstream.fromXML(xmlOut);
	}
 
}

Delete File or folder

To remove a file or a folder: 

HL_webapp/rest/Delete?absPath=$path

Where:

  • absPath: the absolute path of the file/folder to remove.

Output:

  • true: if the file/folder has been correctly removed;
  • false: otherwise.
Retrieved from "https://gcube.wiki.gcube-system.org/index.php?title=Home_Library_REST_API&oldid=27551"