Skip to content

API User Documentation

Jump to bottom
MoDCS Research Group edited this page Apr 25, 2015 · 3 revisions

#How To Use the API

The main purpose of this section is to show all the possible REST Calls supported by Caboclo. For this example, we chose Dropbox as the Cloud Storage Service, therefore the REST Calls are the same for all the other already supported storage services, as well as for any other cloud storage service that the user may desire to implement, because the service is always one of the parameters of the REST invocations.

In order to show how to perform the REST HTTP Requests, we are using a tool to perform the REST invocations, although the user may use any programming language to perform the REST Calls or any other already created REST Client tool. One assumption here is that the user must be authenticated on the Caboclo, in order to use the REST Calls (unless for the Authentication Calls). Also observe that we are going to run the Caboclo Web Server locally, so the IP address on our example will always be 'localhost', at the port 8080.

figure 3.1 Figure 3.1 - showing that the Web Server is up and running

As the Web Server is already running, the first step is to authenticate to the desired Cloud Storage Service.

 @GET
  @Path("{service}/auth/parameters")
  public String getAuthParameters(@PathParam("service") String service)

This GET invocation will return the list of parameters that are needed to perform an authentication to the desired Cloud Storage Service.

figure 3.2 Figure 3.2 - After the GET Request the necessary parameters are returned

The next step is to obtain the service authentication URL.

 @GET
  @Path("{service}/auth/parameters/{parameter}")
  public String getAuthParameters(@PathParam("service") String service, @PathParam("parameter") String parameter)

This GET invocation will return the corresponding parameter passed in the field ‘parameter’, in the example below, it is requested the parameter ‘url’ and the Web Server returns the string regarding the URL for the authentication of the chosen service.

figure 3.3 Figure 3.3 - After the GET Request we receive the Dropbox authentication URL

After entering with the authentication URL in any browser, the user will be requested to allow Caboclo to access your cloud storage service. The user allows and receives the authentication token which should be copied and pasted in the next step, which is the POST authentication REST Call.

figure 3.4

Figure 3.4 - Shows the authentication screen on the browser

 @POST
  @Path("{service}/auth")
  public String authenticate(@PathParam("service") String service, String parameters)

This POST invocation, sends the desired authentication parameters of the determined service to the Caboclo Web Server and it returns "success":true if the authentication was successful, otherwise it returns "success":false.

figure 3.5

Figure 3.5 - Shows selected POST HTTP Method and the URL now is http://localhost:8080/backups/dropbox/auth/

figure 3.6

Figure 3.6 - In the body of the request, we paste the token. Body format:

   {"token":"Egn_UxDflhsAAAAA_SAMPLE_TOKEN_INQRfXnZYcui4"}

Now we already authenticated, but if the user want to make sure that the service is indeed authenticated, it is possible to perform the following REST Call.

 @GET
  @Path("{service}/isauth")
  public String isAuthenticated(@PathParam("service") String service)

This GET invocation will return a "success":true if the determined service is already authenticated, otherwise it returns a "success":false.

figure 3.7

Figure 3.7 - Shows that the user is already authenticated

Now that we are already authenticated, we can start performing backup operations, restore operations, list operations and so forth.

 @GET
  @Path("localhost:8080/backups/{service}/all")
  listAllBackups(@PathParam("service") String service)

This GET invocation will return a list with the names of all the already done backups of the determined cloud storage service. Note that the 'name' of a backup is one of the parameters necessary to perform a restore operation.

figure 3.8

Figure 3.8 - Shows the list of already existing backups

After listing the backups, now let's perform a new backup operation with the following REST invocation.

 @POST
 @Path("{service}/doBackup")
 public String doBackup(@PathParam("service") String service, String body)

This POST invocation performs a backup operation of a folder, or of a single file; The user must post the path to the folder/file in the body of the POST request. Body JSON format:

 {"path":"path/to/your/folder/or/file"}

figure 3.9

Figure 3.9 - Shows the expected format of the body of the POST request (Note that the path format is different under Windows, refer to the appendix for more details). The backup operation REST call returns for the user the 'id' of the Activity and a flag of true or false, regarding the success of the backup operation

Caboclo also supports the backup operation of a list of folders, so that the user can use the following REST call.

 @POST
 @Path("{service}/doBackupMultiObject")
 public String doBackupMultiObject(@PathParam("service") String service, String body)

This POST invocation performs a backup operation of a list of folders; The user must post in the body of the POST request, a list that contains the absolute paths to the folders. Body JSON format:

 {"path":"path/to/your/folder1","path":"path/to/your/folder2","path":"path/to/your/folder3", …}

After the backup operations, the user may perform a restore operation using the following REST invocation.

 @POST
 @Path("{service}/restore")
 public String restoreBackup(@PathParam("service") String service, String body)

This POST invocation performs a restore operation of a previously done backup. The user must post the name of the backup in the body of the POST request, as well as the absolute path of the target folder, which is the local folder where the backup will be restored. One important assumption is that the user performing the restore operation must have read and write permissions on the target folder. Body JSON format:

 {"backupId":"YourBackupNameHere","targetPath":"/target/local/path"}

figure 3.10

Figure 3.10 - Shows the expected format of the body of the POST request (Note that the path format is different under Windows, refer to the appendix for more details)

After the authentication, backups and restore invocations, the user may want to check the list of the current activities and their current status; the user may also want to cancel, pause or resume an activity. The following REST calls deal with the activities of Caboclo.

 @GET
 @Path("{service}/activities")
 public String getActivities(@PathParam("service") String service) { BackupEngine 
  engine = getEngine(service)}

This GET invocation returns a list with the ids of all the current activities on Caboclo.

After listing the current activities ids, the user may want to inspect one individual activity to check its status (Running, Failed, Suspended, Not Started, Canceled or Finished).

 @GET
 @Path("{service}/activity/{id}")
 public String getActivity(@PathParam("service") String service,
        @PathParam("id") String id)

This GET invocation returns the current status of one activity. The user must provide the id of the activity on the path url of the HTTP GET request. The Web Server will return the current status of the informed activity.

Clone this wiki locally