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
Read the Introducing Slingshot blog post (video included) 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
- u user:password |
Slingshot currently uses http authentication. For the curl command to succeed the -u flag is used to pass authorized EVO user to the API. Any valid EVO username can be used, however it is best practice to have a single user specifically for Slingshot.
|
"from": |
The following protocols are valid in the "from" field: evo:/// - Used to access files on a local (EVO) share. Usage: evo:///<share name>/<path>/<file name> smb:// - SMB or Samba, used by Mac and Windows Usage: smb://<server IP or Domain Name>/<share name>/<path>/<file name> afp:// - AFP or Netatalk, used by Mac and Linux Usage: afp://<server IP or Domain Name>/<share name>/<path>/<file name> ftp:// - Any public or local FTP server reachable by EVO Usage: ftp://<server IP or Domain Name>/<path>/<file name>
s3:// - Amazon AWS S3 Service Usage: s3://<region endpoint>/<bucket>/<file name> alias:// - Use credentials predefined in an alias. Usage: alias://<alias name>>/<path>/<file name>
|
"to": |
The following protocols are valid in the "to" field: evo:/// - Used to access files on a local (EVO) share. Usage: evo:///<share name>/<path>/<file name> smb:// - SMB or Samba, used by Mac and Windows Usage: smb://<server IP or Domain Name>/<share name>/<path>/<file name> afp:// - AFP or Netatalk, used by Mac and Linux Usage: afp://<server IP or Domain Name>/<share name>/<path>/<file name> ftp:// - Any public or local FTP server reachable by EVO Usage: ftp://<server IP or Domain Name>/<path>/<file name>
s3:// - Amazon AWS S3 Service Usage: s3://<region endpoint>/<bucket>/<file name> alias:// - Use credentials predefined in an alias. Usage: alias://<alias name>>/<path>/<file name>
|
"source": |
The "source" entry is where credentials need to be entered for the server used in the "from" field. If "evo:///" protocol is being used, a valid EVO user should be entered who has permission to access that share via SMB or AFP.
|
"destination": |
The "destination" entry is where credentials need to be entered for the server used in the "to" field. If "evo:///" protocol is being used, a valid EVO user should be entered who has permission to access that share via SMB or AFP.
|
"metadata": |
The "metadata" section is needed when FTP, or S3 is used. In our example the destination is an FTP server so the "metadata" section is included under "destination".
If S3 is used, the following would need to be included in place of the ftp specific metadata:
example: "s3_region": "eu-west-1"
|
EVO Address |
The EVO IP or Domain Name needs to be defined as part of the curl command.
|
See also: ShareBrowser API