Using CURL to access CloudLayer Storage

CloudLayer Storage is billed as providing "anytime, anywhere access to your data". This isn’t just referring to human interfaces, but also includes automated interfaces.

One easy way to automate access to CloudLayer Storage is through curl. Curl is available as a command-line tool in most every operating system and is typically used for transferring files. In this post I’ll show some examples on how to use curl to add, get, delete, or otherwise manipulate files in CloudLayer Storage. Note that this isn’t using the SoftLayer API, but instead interfaces directly with CloudLayer Storage.

Upload a file named "DSC1012.jpg" to an account owned by username "user@example.com" with a password of "PaSsWoRd":

# curl –F filename=@DSC1012.jpg –u user@example.com:PaSsWoRd \\
https://storage.cloudlayer.com/v1/files/

The command will return some XML tags. The items of interest are "FileID" and "lockID". These values are important for future operations on the file.

<fileID>102C9C28-65C3-11DE-1234-2BE68BA216C2</fileID>
<lockID>6CDCEEB2-6B38-11DE-A510-123F439A2728</lockID>
<lockDuration>120</lockDuration>

The lock is to protect a file form reading or being manipulated during the upload process. The lock will expire in "lockDuration" seconds or the user can disable the lock manually.

Here is how to disable the lock using the lockID and the fileID generated from the upload operation:

# curl –d \\
   'action=unlock&lockid=6CDCEEB2-6B38-11DE-A510-123F439A2728' \\
   –u user@example.com:PaSsWoRd \\
   https://storage.cloudlayer.com/v1/files/102C9C28-65C3-11DE-1234-2BE68BA216C2/lock

If you ever lose track of the FileID, you can use this command to retrieve a listing of the files and containers (directories) in an account along with the FileIDs which are listed as an "oid" XML tag.

# curl –u user@example.com:PaSsWoRd \\
https://storage.cloudlayer.com/v1/files/list

To get the list of files in a container, just append the container oid to the URL.

# curl –u user@example.com:PaSsWoRd \\
https://storage.cloudlayer.com/v1/files/list?oid=37D0F2AC-08FC-11DE-1234-3FA3A91CD1B4

To retrieve the file from CloudLayer Storage, use the FileID to retrieve it.

# curl  -u user@example.com:PaSsWoRd \\
https://storage.cloudlayer.com/v1/files/37D0F2AC-08FC-11DE-1234-3FA3A91C... -o outputfilename

Alternatively, you could use "wget" to retrieve the file

# wget –http-user=user@example.com -–http-password=PaSsWoRd  \\
https://storage.cloudlayer.com/v1/files/37D0F2AC-08FC-11DE-1234-3FA3A91C... -O outputfilename

To delete a file just add the POST form variable "action" with the value "delete".

# curl –d 'action=delete' –u user@example.com:PaSsWoRd \\
https://storage.cloudlayer.com/v1/files/37D0F2AC-08FC-11DE-1234-3FA3A91CD1B4/

Each of the commands listed above return data in XML format. If you would prefer json format, add a query parameter "output=json" to the query string.

# curl –u user@example.com:PaSsWoRd \\
https://storage.cloudlayer.com/v1/files/list?output=json

In order to create a public URL for a file, just send a POST variable of "action=create" to the "token" endpoint.

# curl -d 'action=create' -u user@example.com:PaSsWoRd \\
https://storage.cloudlayer.com/v1/files/37D0F2AC-08FC-11DE-1234-3FA3A91CD1B4/token/

The long string "37D0F2..." is the oid (a.k.a FileID) of the file that you can get from the XML returned when the file was uploaded, or retrived using the file listing example above.

In the XML (or JSON) data that is returned, there will be a "token".

<token>B2891F7B054EF2DF764801E1CFF0079057291234</token>

That token can be combined with the oid to create a URL that anyone can use to retrieve the file.

The URL looks like this:
https://storage.cloudlayer.com/v1/public/{oid}/{token}

In our example it would be:
https://storage.cloudlayer.com/v1/public/37D0F2AC-08FC-11DE-1234-3FA3A91...

If you are accessing CloudLayer Storage from inside a SoftLayer datacenter, you can access the storage over the SoftLayer private network (no bandwidth fees!). Just use "scs.service.softlayer.com" instead of "storage.cloudlayer.com".

You can use the information above in conjunction with the curl libraries in PHP, C++, or one of many other programming languages with curl bindings.