|
|
| (106 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;
| + | |
| − | * '''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>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>
| + | |
| − | </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:
| + | |
| − | <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 ===
| + | |
| − | | + | |
| − | 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.
| + | |
