Slingshot API: Introduction/tutorial (with examples)

What is Slingshot?

Slingshot is an API framework and GUI for the EVO shared storage server. With Slingshot, you can create and run automated file workflows that span EVO, other storage systems, and even cloud storage.

For users, Slingshot has an easy-to-use point and click “Task Builder/Editor” GUI in EVO’s web interface. For developers and integrators, Slingshot includes a powerful API (application programming interface) that enables you to build flexible integrations for a variety of applications.

It’s up to you whether you want to use the Task Editor, the API, or both. If you want easy-to-use, scheduled automations, use the Task Builder. If you need advanced, on-demand automations, use the API.

Slingshot includes a Rest API and as such utilizes HTTP methods (GET, POST, PUT, and DELETE) to listen for commands or requests for information. A full list of available commands and syntax can be found on Slingshot-enabled EVO systems. With Slingshot installed, navigate to the API to access the interactive documentation for your version:

EVO version 6 - http://<EVO_Address>/static/swagger

EVO version 7 - http://<EVO_Address>/v1/swagger/#/

Check out our Slingshot page for a broader overview of Slingshot's capabilities.

Purpose of this article

This article is an introduction to using the API component of Slingshot. Almost all API uses will involve the Transporter — a versatile command for transferring files. A tutorial is included to demonstrate the process of creating a Transporter operation that copies a file from a local share on EVO to an FTP server.

The cURL command can be used within a macOS Terminal and will be used in this example to demonstrate direct interactions with the Slingshot API using standard http methods. The Slingshot API can interact using other tools that use standard http methods and authentication and can be integrated programmatically.

This article is intended for readers who are comfortable using an API.  

Listing

Let's start by looking at a few GET commands that may come in handy when constructing a transporter.

Listing a Share - GET

curl -u user:password -X GET --header 'Accept: application/json' 'http://192.168.51.8/v1/share'

Click on any part of the command examples that show as a link to see a more detailed description and how it should be modified for use in another environment.

The word "share" after "/v1/" is important as this is the actual command being requested.

Response Body:

[
    {
        "name": "AF8",
        "partition": 1,
        "pool": "POOL-A",
        "uuid": "52d6a87c-c518-4001-ab79-a9ecefc974bd",
        "volume": "d1r0"
    },
    {
        "name": "Apple8",
        "partition": 1,
        "pool": "POOL-A",
        "uuid": "c1689421-3898-4f03-98c2-4ccbca1d54df",
        "volume": "d0r0"
    },
    {
        "name": "SM8",
        "partition": 1,
        "pool": "POOL-A",
        "uuid": "5e519eae-bb33-441c-9b51-655c2792d1d1",
        "volume": "d1r0"
    },
    {
        "name": "Sam8",
        "partition": 1,
        "pool": "POOL-A",
        "uuid": "10ca0eda-f33d-49e5-8a94-5f688d246bcb",
        "volume": "d0r0"
    }
]

/v1/share

This command requests a list of all NAS shares available on an EVO located at http://192.168.51.8.

A successful execution of this command in the macOS Terminal should display the response body in the form of json data.

The data returned in the response body should include:

• name
• Name of a NAS share
• partition
• On which partition the share is located
• pool
• Name of the Pool where the volume is located
• uuid
• UUID of the share
• volume
• Volume name on which the share is located

List Contents of a Share - GET

curl -u user:password -X GET --header 'Accept: application/json' 'http://192.168.51.8/v1/share/Apple8/file/'

Response Body:

[ {
    "exists" : true,
    "name" : ".TemporaryItems",
    "type" : "FOLDER"
}, {
    "exists" : true,
    "name" : "001a",
    "type" : "FOLDER"
}, {
    "exists" : true,
    "name" : "001b",
    "type" : "FOLDER"
} ]

v1/share/{share_name}/file/

This command builds upon the List Share command by adding a valid share name (Apple8) and "/file/" after "/share/". In this case "/file/" is a command and should not be replaced by a filename.

Details about files and folders in the root level of the share will be returned in the response body. A valid share name for which the user has permission to access must be used, otherwise the response will be empty.

List Contents of a Directory - GET

curl -u user:password -X GET --header 'Accept: application/json' 'http://192.168.51.8/v1/share/Apple8/file/001a'

Response Body:

[ {
    "exists" : true,
    "length" : 0,
    "name" : "otherFile.txt",
    "type" : "FILE"
}, {
    "exists" : true,
    "length" : 26214400,
    "name" : "mix.zip",
    "type" : "FILE"
} ]

v1/share/{share_name}/file/{directory_name}

This command further builds upon the "v1/share/" command by adding a directory name (001a) after "/file/". Just like the previous example this should return details about files or folders that exist within the specified directory.

This particular directory contains two files; mix.zip is the one we want to send to an FTP server. Note the size in bytes (length) of each file — this can be useful for verification.

If the directory is empty, the command should return an empty body: []

If an invalid directory is specified an error may be returned:

{"errorMessage":"Failed to get file list."}

As we'll see shortly the Transporter command handles individual files. Multiple Transporter commands can be called if multiple files need to be handled. The json output of v1/share/Apple8/file/001a can be used to construct Transporter commands that cover every file in a directory or any method of filtering that can be applied using bash or another program language.

Transporter
 

New Transporter - POST

At the heart of the Slingshot API is the Transporter command. Each time a file is moved, copied, renamed, or removed by an Automation, Transporter is the command used by Slingshot to carry it out.

curl -u user:password -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "request": {
     "from": "evo:///Apple8/001a/mix.zip",
     "to": "ftp://90.130.70.73/upload/mix.zip"
     },
   "source": {
     "user": "user",
     "password": "password"
   },
   "destination": {
     "user": "user",
     "password": "password",
     "metadata": {
       "ftp_user_dir_is_root": false,
       "ftp_passive": true
     }
   }
 }' 'http://192.168.51.8/v1/transporter'

Response Body:

{
  "transfer_id" : 4102
}

v1/transporter

In this case, we are requesting that a transporter be created (POST) to copy a file from a local share on EVO to an FTP server located at ftp://90.130.70.73.

Note that the only data returned is the "transfer_id". Most file operations will take longer to complete than is practical to wait for a response from an http request. The transporter POST will not report the status of the file operation, instead it simply returns the "transfer_id". This does not indicate that the file has been transferred; the transfer_id confirms that the command was processed successfully. Errors can be returned if the command was not structured properly.

Verification - GET
 

curl -u user:password -X GET --header 'Accept: application/json' 'http://192.168.51.8/v1/transporter/4102'

Response Body:

{
  "eta" : 0,
  "finished" : "2017-03-27T23:01:42.575Z",
  "id" : 4102,
  "location" : "ftp://192.168.79.81/public_ftp_server///public_ftp_server/mix.zip",
  "message" : "File uploaded successfully",
  "name" : "4102",
 "request" : {
 "from" : "evo:///Apple8/001a/mix.zip",
 "to" : "ftp://172.19.79.81/public_ftp_server/mix.zip",
 "decomposed_from" : {
  },
 "decomposed_to" : {
 }
 },
 "started" : "2017-03-27T23:01:41.616Z",
 "status" : "SUCCEED",
 "total" : 26214400,
 "transferred" : 26214400
}

v1/transporter/{transfer_id}

Using the transfer_id obtained in the previous example we can check the status of the operation.

The information about the Transporter that gets returned is very useful for tracking, logging, and debugging. Checking the transfer_id can be be done very quickly, so calling it multiple times to check multiple transfers can be a good way to monitor activity and keep track of what is queued, active, and complete.

To ease the process of debugging we've included multiple elements that can be used to diagnose unexpected results.

We can see three indications of success in the example response.

• "message"
• Human readable message that may contain verbose errors.
• "status"
• Short (single word) description of the status
• "transferred"
• Number of bytes transferred in this operation

Definitions

See also: ShareBrowser API