|
|
| (94 intermediate revisions by 6 users not shown) |
| Line 1: |
Line 1: |
| − | = Overview = | + | == The Home Library has been deprecated by the new [https://wiki.gcube-system.org/gcube/StorageHub_REST_API StorageHub Service] == |
| − | | + | Please use the StorageHub service for future developments: https://wiki.gcube-system.org/gcube/StorageHub_REST_API |
| − | 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;
| + | |
| − | * '''Download''': to download a file or a folder in ZIP format;
| + | |
| − | * '''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.
| + | |
| − | *HL_WEBAPP next: https://workspace-repository-dev.research-infrastructures.eu/home-library-webapp
| + | |
| − | *HL_WEBAPP preProd: http://ws-repo-test.d4science.org/home-library-webapp
| + | |
| − | | + | |
| − | === Create Folder ===
| + | |
| − | | + | |
| − | To create a new folder:
| + | |
| − | <source lang="java">
| + | |
| − | HL_WEBAPP/rest/CreateFolder?name=$name&description=$desc&parentPath=$path
| + | |
| − | </source>
| + | |
| − | | + | |
| − | 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:
| + | |
| − | | + | |
| − | <source lang="java">
| + | |
| − | HL_WEBAPP/rest/CreateFolder?name=myFolder&description=myDescription&parentPath=/Home/valentina.marioli/Workspace/MyDocs/
| + | |
| − | </source>
| + | |
| − | | + | |
| − | === List ===
| + | |
| − | To list the content of a folder:
| + | |
| − | <source lang="java">
| + | |
| − | HL_WEBAPP/rest/List?absPath=$path
| + | |
| − | </source>
| + | |
| − | | + | |
| − | Where:
| + | |
| − | * '''absPath''': the absolute path of the folder to list.
| + | |
| − | | + | |
| − | Example:
| + | |
| − | | + | |
| − | <source lang="java">
| + | |
| − | HL_WEBAPP/rest/List?absPath=/Home/valentina.marioli/Workspace/MySpecialFolders/gcube-devNext-NextNext/
| + | |
| − | </source>
| + | |
| − | 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.
| + | |
| − | | + | |
| − | | + | |
| − | <source lang="xml">
| + | |
| − | <map>
| + | |
| − | <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>home-library-2.5.0-SNAPSHOT.jar</string>
| + | |
| − | <boolean>false</boolean>
| + | |
| − | </entry>
| + | |
| − | <entry>
| + | |
| − | <string>home-library-common-2.5.0-SNAPSHOT.jar</string>
| + | |
| − | <boolean>false</boolean>
| + | |
| − | </entry>
| + | |
| − | <entry>
| + | |
| − | <string>anotherFolder</string>
| + | |
| − | <boolean>true</boolean>
| + | |
| − | </entry>
| + | |
| − | </map>
| + | |
| − | </source>
| + | |
| − | | + | |
| − | === Upload File ===
| + | |
| − | | + | |
| − | To upload a file, if it does not already exist:
| + | |
| − | <source lang="java">
| + | |
| − | HL_WEBAPP/rest/Upload?name=$name&description=$description&parentPath=$path
| + | |
| − | </source>
| + | |
| − | | + | |
| − | 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:
| + | |
| − | <source lang="java">
| + | |
| − | HL_WEBAPP/rest/Upload?name=$name&description=$description&parentPath=$path&mimetype=$mimetype&size=$size
| + | |
| − | </source>
| + | |
| − | | + | |
| − | You have to attach the file as mutipart content of your request.
| + | |
| − | | + | |
| − | Example in Java language:
| + | |
| − | <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/test.user/Workspace/";
| + | |
| − | | + | |
| − | public static void main(String[] args) throws Exception {
| + | |
| − |
| + | |
| − | SecurityTokenProvider.instance.set(HERE_YOUR_TOKEN);
| + | |
| − | URL imageURL = UploadFileRest.class.getClassLoader().getResource(DEFAULT_IMAGE);
| + | |
| − | File file = new File(imageURL.getFile());
| + | |
| − | | + | |
| − | byte[] image = Files.readAllBytes(file.toPath());
| + | |
| − | System.out.println(uploadFile(image, DEFAULT_IMAGE, "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>
| + | |
| − | | + | |
| − | === Download ===
| + | |
| − | | + | |
| − | To download a file or a folder in ZIP format:
| + | |
| − | <source lang="java">
| + | |
| − | HL_WEBAPP/rest/Download?absPath=$path
| + | |
| − | </source>
| + | |
| − | | + | |
| − | Where:
| + | |
| − | * '''absPath''': the absolute path of the file/folder to download.
| + | |
| − | | + | |
| − | Output:
| + | |
| − | * '''a file''': if the item to download is a file;
| + | |
| − | * '''a compressed zipped folder''': if the item to download is a folder.
| + | |
| − | | + | |
| − | Example in Java language:
| + | |
| − | | + | |
| − | <source lang="java">
| + | |
| − | import java.io.File;
| + | |
| − | import java.io.FileOutputStream;
| + | |
| − | import java.io.IOException;
| + | |
| − | import java.io.InputStream;
| + | |
| − | import java.net.HttpURLConnection;
| + | |
| − | import java.net.URL;
| + | |
| − |
| + | |
| − | /**
| + | |
| − | * A utility that downloads a file from a URL.
| + | |
| − | *
| + | |
| − | */
| + | |
| − | public class HttpDownloadUtility {
| + | |
| − | private static final int BUFFER_SIZE = 4096;
| + | |
| − |
| + | |
| − | /**
| + | |
| − | * Downloads a file from a URL
| + | |
| − | * @param fileURL HTTP URL of the file to be downloaded
| + | |
| − | * @param saveDir path of the directory to save the file
| + | |
| − | * @throws IOException
| + | |
| − | */
| + | |
| − | public static void downloadFile(String fileURL, String saveDir)
| + | |
| − | throws IOException {
| + | |
| − | URL url = new URL(fileURL);
| + | |
| − | HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
| + | |
| − | int responseCode = httpConn.getResponseCode();
| + | |
| − |
| + | |
| − | // always check HTTP response code first
| + | |
| − | if (responseCode == HttpURLConnection.HTTP_OK) {
| + | |
| − | String fileName = "";
| + | |
| − | String disposition = httpConn.getHeaderField("Content-Disposition");
| + | |
| − | String contentType = httpConn.getContentType();
| + | |
| − | int contentLength = httpConn.getContentLength();
| + | |
| − |
| + | |
| − | if (disposition != null) {
| + | |
| − | // extracts file name from header field
| + | |
| − | int index = disposition.indexOf("filename=");
| + | |
| − | if (index > 0) {
| + | |
| − | fileName = disposition.substring(index + 10,
| + | |
| − | disposition.length() - 1);
| + | |
| − | }
| + | |
| − | } else {
| + | |
| − | // extracts file name from URL
| + | |
| − | fileName = fileURL.substring(fileURL.lastIndexOf("/") + 1,
| + | |
| − | fileURL.length());
| + | |
| − | }
| + | |
| − |
| + | |
| − | System.out.println("Content-Type = " + contentType);
| + | |
| − | System.out.println("Content-Disposition = " + disposition);
| + | |
| − | System.out.println("Content-Length = " + contentLength);
| + | |
| − | System.out.println("fileName = " + fileName);
| + | |
| − |
| + | |
| − | // opens input stream from the HTTP connection
| + | |
| − | InputStream inputStream = httpConn.getInputStream();
| + | |
| − | String saveFilePath = saveDir + File.separator + fileName;
| + | |
| − |
| + | |
| − | // opens an output stream to save into file
| + | |
| − | FileOutputStream outputStream = new FileOutputStream(saveFilePath);
| + | |
| − |
| + | |
| − | int bytesRead = -1;
| + | |
| − | byte[] buffer = new byte[BUFFER_SIZE];
| + | |
| − | while ((bytesRead = inputStream.read(buffer)) != -1) {
| + | |
| − | outputStream.write(buffer, 0, bytesRead);
| + | |
| − | }
| + | |
| − |
| + | |
| − | outputStream.close();
| + | |
| − | inputStream.close();
| + | |
| − |
| + | |
| − | System.out.println("File downloaded");
| + | |
| − | } else {
| + | |
| − | System.out.println("No file to download. Server replied HTTP code: " + responseCode);
| + | |
| − | }
| + | |
| − | httpConn.disconnect();
| + | |
| − | }
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | | + | |
| − | === Delete File or folder ===
| + | |
| − | | + | |
| − | To remove a file or a folder:
| + | |
| − | <source lang="java">
| + | |
| − | HL_WEBAPP/rest/Delete?absPath=$path
| + | |
| − | </source>
| + | |
| − | | + | |
| − | Where:
| + | |
| − | * '''absPath''': the absolute path of the file/folder to remove.
| + | |
| − | | + | |
| − | Output:
| + | |
| − | * '''true''': if the file/folder has been correctly removed;
| + | |
| − | * '''false''': otherwise.
| + | |
