NAV Navbar
Logo primary

Seagate Lyve Cloud API Reference

shell

Contents

Introduction

This document describes the APIs offered by Seagate. The APIs are, where possible, modelled after the ones offered by AWS, to maximize interoperability with existing tools. The differences with the AWS APIs are explicitly noted.

Authentication

The provided APIs are authenticated via AWS Signature V4, using an access_key, secret_key pair. Requests can be signed either using any SDK compatible with AWS.

Credentials management (STS)

The STS endpoint (https://sts.example.rstorcloud.io) allows managing temporary user tokens and performing login with username and password. Requests to the STS endpoint must be signed specifying "sts" as service.

Get a set of temporary keys for a user with access/secret keys: (AssumeRole)

Example Request

POST / HTTP/1.1
Host: sts.example.rstorcloud.io
Content-Length: 80
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Authorization: [...]
X-Amz-Date: [...]

Action=AssumeRole&RoleArn=Required1&RoleSessionName=Required2&Version=2011-06-15

Response

<AssumeRoleResponse xmlns="https://sts.amazonaws.com/doc/2011-06-15/">
 <AssumeRoleResult>
  <Credentials>
   <SessionToken>42</SessionToken>
   <SecretAccessKey>EXAMPLESECRETACCESSKEYXXXXXXXXXXXXXXXXXXXXXXXXI6GGPQ</SecretAccessKey>
   <Expiration>2019-02-25T14:40:05.410Z</Expiration>
   <AccessKeyId>AWS4XXXEXAMPLEACCESSKEYID4UYJN3RQWFVFXBOP7FMOQLIXYZXYZ</AccessKeyId>
  </Credentials>
  <AssumedRoleUser>
   <Arn>arn:aws:sts::42:assumed-role/demo/Test</Arn>
   <AssumeRoleId>AWS4XXXEXAMPLEACCESSKEYID4UYJN3RQWFVFXBOP7FMOQLIDNXYZXYZ:Jim</AssumeRoleId>
  </AssumedRoleUser>
  <PackedPolicySize>42</PackedPolicySize>
 </AssumeRoleResult>
 <ResponseMetadata>
  <RequestId>42</RequestId>
 </ResponseMetadata>
</AssumeRoleResponse>

POST /?Action=AssumeRole

POST Parameters

Parameter Description
Action must be set to AssumeRole
Version must be set to 2011-06-15
DurationSeconds token validity in seconds, between 15 minutes and 12 hours. Defaults to 15 minutes
RoleSessionName required but ignored
RoleArn required but ignored

Response

On success, an XML document containing the requested credentials at AssumeRoleResult/Credentials is returned. An error status code is returned otherwise.

RSLogin

Perform a login retrieving the credential and the user details.

Parameter Description
Customer the name of the customer
UserName the username (can be the email) of the user
Password the current user password
OTP a valid One Time Password (if needed)
DurationSeconds specify the duration of the session (the validity time for the key)

Extra headers used to authenticate the request when whitelisting is enabled:

Header Description
x-rstor-customer specify the customer name

Example request

POST / HTTP/1.1
Host: sts.rstorcloud.io
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:69.0) Gecko/20100101 Firefox/69.0
Accept: application/json, text/plain, */*
Accept-Language: en,it-IT;q=0.8,it;q=0.5,en-US;q=0.3
Accept-Encoding: gzip, deflate, br
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 123
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache
x-rstor-customer: fastvideo

Action=RSLogin&Version=2011-06-15&DurationSeconds=300&Customer=fastvideo&UserName=super@fastvideo.com&Password=Hg27TxBBfOzZntb&OTP=

Example response

{
  "RequestId":"050517212914402dd8aedfc50bb0dad0",
  "Credentials": {
    "SessionToken":"",
    "SecretAccessKey":"I/Ki9fZqmLkdWrAgIrKVdp6amEu9Q40CoRPVNpSeKVS",
    "Expiration":"2019-10-14T14:13:03.500533224Z",
    "AccessKeyId":"RSTOR09VFCSKU9OZJY5Y4PLWD9"
  },
  "UserInfo":{
    "Id":"100000000209",
    "Name":"super@fastvideo.com",
    "PwdMustChange":false,
    "Email":"super@fastvideo.com",
    "Firstname":"Clark",
    "Lastname":"Kent",
    "Type":"user",
    "CreatedOn":"2019-10-03T15:37:52.635Z",
    "LastAccess":"2019-10-14T13:13:03.500533224Z",
    "Path":"",
    "Root":"rstor:fastvideo",
    "TFAEnabled":false
  }
}

RSAssumeCustomerRole

Retrieve credential to manage a Customer with AssumeRole enabled. In order to perform this action a specific account is used for security reason. Only a reseller account can perform this action.

Parameter Description
Customer the name of the customer
DurationSeconds specify the duration of the session (the validity time for the key)

Example request

POST / HTTP/1.1
Host: sts.rstorcloud.io
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:69.0) Gecko/20100101 Firefox/69.0
Accept: application/json, text/plain, */*
Accept-Language: en,it-IT;q=0.8,it;q=0.5,en-US;q=0.3
Accept-Encoding: gzip, deflate, br
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 83
Connection: keep-alive
Pragma: no-cache
Cache-Control: no-cache

Action=RSAssumeCustomerRole&Version=2011-06-15&Customer=newcorp&DurationSeconds=300

Example response

{
  "Ok":true,
  "AccessKeyId":"RSTOR06MSKQJCRTS4SJHHQJWOP",
  "SecretAccessKey":"RQTcszgc4xkZkmYXRJJLYR7adksTn8SBIalTP7rrpKa",
  "Expiration":"2019-10-14T14:29:43.919Z"
}

User management (IAM)

The IAM endpoint (https://iam.example.rstorcloud.io) allows managing user accounts and permissions. Requests to the IAM endpoint must be signed specifying "iam" as service.

User

A user can access the system either by logging in via email and password, or via one of its access keys, and perform actions according to its role and attached policies. Note that, for all users, the username coincides with the email.

A user belong to one of the following roles:

Role Description
Root is the initial and main user of the account, has permissions on all buckets, and is able to manage users and policies. It cannot be deleted
Admin can manage users and policies, with the exception of the Root account
User can perform operations on buckets according to the policies it is attached. It can change its own password, create and revoke its own access keys

Policies

A policy defines a set of permissions on buckets, and can be attached to a set of users.

AttachUserPolicy

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: 86
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=AttachUserPolicy&PolicyArn=arn:aws:iam::000000000000:policy/SomePolicy&UserName=user@example.com&Version=2010-05-08

Example response

<AttachUserPolicyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>gf7hb0r6v5ix</RequestId>
 </ResponseMetadata>
</AttachUserPolicyResponse>

Attaches a policy to a user

POST parameters

Parameter Description
Action must be set to AttachUserPolicy
Version must be set to 2010-05-08
UserName name of the user the policy will be attached to
PolicyArn ARN of the policy to attach

ChangePassword

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: 86
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=ChangePassword&OldPassword=Password00&NewPassword=Password01&Version=2010-05-08

Example response

<ChangePasswordResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
  <ResponseMetadata>
    <RequestId>EXAMPLE</RequestId>
  </ResponseMetadata>
</ChangePasswordResponse>

Changes the password of the user making the request. It requires providing the old password.

POST parameters

Parameter Description
Action must be set to ChangePassword
Version must be set to 2010-05-08
OldPassword old password of the current user
NewPassword new password for the current user. Must be at least 10 characters and contain numbers, lowercase and uppercase letters

CreateAccessKey

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=CreateAccessKey&UserName=user@example.com&Version=2010-05-08

Example response

<CreateAccessKeyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>830kau3a8zis</RequestId>
 </ResponseMetadata>
 <CreateAccessKeyResult>
  <AccessKey>
   <UserName>user@example.com</UserName>
   <AccessKeyId>AWS4AKIAKMEQGHROSDH7BKLB4QMNZAVANP4PGEZYJSWPBI4P4GTWGXDC</AccessKeyId>
   <Status>Active</Status>
   <SecretAccessKey>HCXL33NNPWX2EVEFHUZIGM234UJ64PUP2444OIFE3EOZHGVUG2GQ</SecretAccessKey>
  </AccessKey>
 </CreateAccessKeyResult>
</CreateAccessKeyResponse>

Creates a new access key for the specified user

POST parameters

Parameter Description
Action must be set to CreateAccessKey
Version must be set to 2010-05-08
UserName username of the user for whom the access key should be created. If not specified, it defaults to the user making the request

CreatePolicy

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=CreatePolicy
&Description=Gives all permissions for the bucket "abc-bucket"
&Path=/
&PolicyDocument={"Statement":[{"Action":["s3:GetObject","s3:PutObject","s3:DeleteObject","s3:ListBucket"],"Effect":"Allow","Resource":"arn:aws:s3:::abc-bucket*"},{"Action":["s3:ListAllMyBuckets"],"Effect":"Allow","Resource":"*"}],"Version":"2012-10-17","Managed":true}
&PolicyName=NewPolicy4567
&Version=2010-05-08

Example response

<CreatePolicyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>zd167x71f527</RequestId>
 </ResponseMetadata>
 <CreatePolicyResult>
  <Policy>
   <PolicyName>NewPolicy4567</PolicyName>
   <DefaultVersionId>v1</DefaultVersionId>
   <PolicyId>ANPASMVHTBHTUB7AMZUTK</PolicyId>
   <Path>/</Path>
   <Arn>arn:aws:iam::000000000000:policy/NewPolicy4567</Arn>
   <AttachmentCount>0</AttachmentCount>
   <CreateDate>2019-03-25T09:16:31.497Z</CreateDate>
   <UpdateDate>2019-03-25T09:16:31.497Z</UpdateDate>
   <Description></Description>
  </Policy>
 </CreatePolicyResult>
</CreatePolicyResponse>

Creates a new policy. Note that, except for the PolicyDocument, the other parameters cannot be updated after creation.

POST parameters

Parameter Description
Action must be set to CreatePolicy
Version must be set to 2010-05-08
Description user friendly description of the policy
PolicyDocument policy document in the AWS policy format
PolicyName name for the new policy

CreatePolicyVersion

Updates a policy, creating a new version

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=CreatePolicyVersion
&PolicyArn=arn:aws:iam::000000000000:policy/NewPolicy4567
&PolicyDocument={"Statement":[{"Action":["s3:GetObject","s3:ListBucket"],"Effect":"Allow","Resource":"*"},{"Action":["s3:ListAllMyBuckets"],"Effect":"Allow","Resource":"*"}],"Version":"2012-10-17"}
&SetAsDefault=true
&Version=2010-05-08

Example response

<CreatePolicyVersionResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>kbslm8tegjc8</RequestId>
 </ResponseMetadata>
 <CreatePolicyVersionResult>
  <PolicyVersion>
   <IsDefaultVersion>true</IsDefaultVersion>
   <VersionId>vGRC019YCN3QZ</VersionId>
   <CreateDate>2019-03-25T09:16:31.497Z</CreateDate>
  </PolicyVersion>
 </CreatePolicyVersionResult>
</CreatePolicyVersionResponse>

POST parameters

Parameter Description
Action must be set to CreatePolicyVersion
Version must be set to 2010-05-08
SetAsDefault if set to true, sets the new version as default, making it in effect
PolicyDocument policy document in the AWS policy format
PolicyArn ARN of the policy to update

CreateUser

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=CreateUser&UserName=user2@example.com&Version=2010-05-08

Example response

<CreateUserResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>t3v4bkwxvk0k</RequestId>
 </ResponseMetadata>
 <CreateUserResult>
  <User>
   <Path></Path>
   <UserName>cshhkvuc3sym@example.com</UserName>
   <UserId>100000000546</UserId>
   <Arn>arn:aws:iam::000000000000:user/cshhkvuc3sym@example.com</Arn>
  </User>
 </CreateUserResult>
</CreateUserResponse>

Creates a new user with the specified email address

POST parameters

Parameter Description
Action must be set to CreateUser
Version must be set to 2010-05-08
UserName email of the user to create

DeleteAccessKey

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

AccessKeyId=AWS4AKIAUAAECGIBEUZO3FG2GZBERAAGU2RXEVJYATF2A5XYSYCHCK4V
&Action=DeleteAccessKey
&UserName=user2@example.com
&Version=2010-05-08

Example response

<DeleteAccessKeyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>wztbdx32kks5</RequestId>
 </ResponseMetadata>
</DeleteAccessKeyResponse>

Deletes the specified access key. Both the email of the user the key belongs to and the access key id should be specified. If the email of the user is not provided, it defaults to the user making the request.

POST parameters

Parameter Description
Action must be set to DeleteAccessKey
Version must be set to 2010-05-08
UserName email of the user whose access key should be deleted
AccessKeyId id of the access key to delete

DeletePolicy

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=DeletePolicy
&PolicyArn=arn:aws:iam::000000000000:policy/TestA24152
&Version=2010-05-08

Example response

<DeletePolicyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>alweq16xfjj9</RequestId>
 </ResponseMetadata>
</DeletePolicyResponse>

Deletes the specified policy, if this is not attached to any user, and all of its previous versions (if any) have been previously deleted. You can use respectively DetachUserPolicy and DeletePolicyVersion to detach the policy from users, and to remove the previous policy versions.

POST parameters

Parameter Description
Action must be set to DeletePolicy
Version must be set to 2010-05-08
PolicyArn ARN of the policy to delete

DeletePolicyVersion

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=DeletePolicy
&PolicyArn=arn:aws:iam::000000000000:policy/TestA24152
&VersionId=vMFW10Z4EF4HL
&Version=2010-05-08

Example response

<DeletePolicyVersionResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>caonjqj712u7</RequestId>
 </ResponseMetadata>
</DeletePolicyVersionResponse>

Deletes the specified policy, if this is not attached to any user, and all of its previous versions (if any) have been previously deleted. You can use respectively DetachUserPolicy and DeletePolicyVersion to detach the policy from users, and to remove the previous policy versions.

POST parameters

Parameter Description
Action must be set to DeletePolicyVersion
Version must be set to 2010-05-08
PolicyArn ARN of the policy whose version you wish to delete
VersionId ID of the version to delete, as returned by GetPolicy or ListPolicyVersions

DeleteUser

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=DeleteUser
&UserName=TestUser256@example.com
&Version=2010-05-08

Example response

<DeleteUserResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>5tk62707tkxv</RequestId>
 </ResponseMetadata>
</DeleteUserResponse>

Deletes the specified user. Note that before deleting the user, you must first delete all of its keys, and detach all policies from it. Note also that a user cannot delete itself, and that a root user cannot be deleted.

POST parameters

Parameter Description
Action must be set to DeletePolicyVersion
Version must be set to 2010-05-08
UserName email of the user to delete

DetachUserPolicy

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=DetachUserPolicy
&PolicyArn=arn:aws:iam::000000000000:policy/ABCABC
&UserName=user1@example.com
&Version=2010-05-08

Example response

<DetachUserPolicyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>a95qpalps1gc</RequestId>
 </ResponseMetadata>
</DetachUserPolicyResponse>

Detaches a policy from a user

POST parameters

Parameter Description
Action must be set to DetachUserPolicy
Version must be set to 2010-05-08
UserName email of the user to delete
PolicyArn ARN of the policy the to detach

GetPolicy

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=GetPolicy
&PolicyArn=arn:aws:iam::000000000000:policy/ABCABC
&Version=2010-05-08

Example response

<GetPolicyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>1hxikd7dm49b</RequestId>
 </ResponseMetadata>
 <GetPolicyResult>
  <Policy>
   <PolicyName>ABCABC</PolicyName>
   <DefaultVersionId>vMFW10Z4EF4HL</DefaultVersionId>
   <PolicyId>ANVAP1OHCTVKCZR4TWB3F</PolicyId>
   <Path>/</Path>
   <Arn>arn:aws:iam::000000000000:policy/ABCABC</Arn>
   <AttachmentCount>2</AttachmentCount>
   <CreateDate>2019-03-14T11:23:36.776Z</CreateDate>
   <UpdateDate>2019-03-14T11:23:36.776Z</UpdateDate>
   <Description>policy description</Description>
  </Policy>
 </GetPolicyResult>
</GetPolicyResponse>

Gets metadata about a given policy

POST parameters

Parameter Description
Action must be set to GetPolicy
Version must be set to 2010-05-08
PolicyArn ARN of the policy

GetPolicyVersion

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=GetPolicyVersion
&PolicyArn=arn:aws:iam::000000000000:policy/ABCABC
&Version=2010-05-08
&VersionId=vMFW10Z4EF4HL

Example response

<GetPolicyVersionResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>s9h55m6gm6st</RequestId>
 </ResponseMetadata>
 <GetPolicyVersionResult>
  <PolicyVersion>
   <Document>{&#34;Statement&#34;:[{&#34;Action&#34;:[&#34;s3:GetObject&#34;,&#34;s3:PutObject&#34;,&#34;s3:DeleteObject&#34;,&#34;s3:ListBucket&#34;],&#34;Effect&#34;:&#34;Allow&#34;,&#34;Resource&#34;:&#34;arn:aws:s3:::testbucket*&#34;},{&#34;Action&#34;:[&#34;s3:PutObject&#34;,&#34;s3:DeleteObject&#34;],&#34;Effect&#34;:&#34;Allow&#34;,&#34;Resource&#34;:&#34;arn:aws:s3:::abc-bucket*&#34;},{&#34;Action&#34;:[&#34;s3:ListAllMyBuckets&#34;],&#34;Effect&#34;:&#34;Allow&#34;,&#34;Resource&#34;:&#34;*&#34;}],&#34;Version&#34;:&#34;2012-10-17&#34;,&#34;Managed&#34;:true}</Document>
   <IsDefaultVersion>true</IsDefaultVersion>
   <VersionId>vMFW10Z4EF4HL</VersionId>
   <CreateDate>2019-03-14T11:23:36.776Z</CreateDate>
  </PolicyVersion>
 </GetPolicyVersionResult>
</GetPolicyVersionResponse>

Gets the specified policy version, with its policy document

POST parameters

Parameter Description
Action must be set to GetPolicyVersion
Version must be set to 2010-05-08
PolicyArn ARN of the policy
VersionId ID of the policy version

ListAccessKeys

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=ListAccessKeys
&UserName=user@example.com
&Version=2010-05-08

Example response

<ListAccessKeysResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>hhbsxpz2r66y</RequestId>
 </ResponseMetadata>
 <ListAccessKeysResult>
  <AccessKeyMetadata>
   <member>
    <UserName>user@example.com</UserName>
    <AccessKeyId>AWS4AKIANWYVBGWUGE2PQY7HPOH4QNI6SDDSA6UPQFCTRFLHVCKBZCGA</AccessKeyId>
    <Status>Active</Status>
    <CreateDate>2019-03-15T16:56:56.434Z</CreateDate>
   </member>
   <member>
    <UserName>user@example.com</UserName>
    <AccessKeyId>AWS4AMQVFJACLX5R6FCBRFR3Z2LMYP5KBFBQCVQW3JFARBENYJC6SLZA</AccessKeyId>
    <Status>Active</Status>
    <CreateDate>2019-03-14T12:00:30.358Z</CreateDate>
   </member>
  </AccessKeyMetadata>
  <UserName>user@example.com</UserName>
  <IsTruncated>false</IsTruncated>
 </ListAccessKeysResult>
</ListAccessKeysResponse>

Retrieves a list of the access keys belonging to a given user

POST parameters

Parameter Description
Action must be set to ListAccessKeys
Version must be set to 2010-05-08
UserName email of the user whose access keys should be listed

ListAttachedUserPolicies

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=ListAttachedUserPolicies
&UserName=user@example.com
&Version=2010-05-08

Example response

<ListAttachedUserPoliciesResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>6brrrkcl3nem</RequestId>
 </ResponseMetadata>
 <ListAttachedUserPoliciesResult>
  <AttachedPolicies>
   <member>
    <PolicyName>Policy1</PolicyName>
    <PolicyArn>arn:aws:iam::000000000000:policy/Policy1</PolicyArn>
   </member>
  </AttachedPolicies>
  <IsTruncated>false</IsTruncated>
  <Marker></Marker>
 </ListAttachedUserPoliciesResult>
</ListAttachedUserPoliciesResponse>

Retrieves a list of the policies attached to a given user

POST parameters

Parameter Description
Action must be set to ListAttachedUserPolicies
Version must be set to 2010-05-08
UserName email of the user whose attached policies should be listed

ListEntitiesForPolicy

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=ListEntitiesForPolicy
&PolicyArn=arn:aws:iam::000000000000:policy/ABCABC
&Version=2010-05-08

Example response

<ListEntitiesForPolicyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>7pzdvnk5er4i</RequestId>
 </ResponseMetadata>
 <ListEntitiesForPolicyResult>
  <PolicyUsers>
   <member>
    <UserName>user2@example.com</UserName>
   </member>
   <member>
    <UserName>user@example.com</UserName>
   </member>
  </PolicyUsers>
  <PolicyRoles>
  </PolicyRoles>
  <PolicyGroups>
  </PolicyGroups>
  <IsTruncated>false</IsTruncated>
 </ListEntitiesForPolicyResult>
</ListEntitiesForPolicyResponse>

Retrieves a list of all the users the specified policy is attached to

POST parameters

Parameter Description
Action must be set to ListEntitiesForPolicy
Version must be set to 2010-05-08
PolicyArn ARN of the policy

ListPolicies

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=ListPolicies
&Version=2010-05-08

Example response

<ListPoliciesResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>s5eb8nlvydf2</RequestId>
 </ResponseMetadata>
 <ListPoliciesResult>
  <Policies>
   <member>
    <PolicyName>Policy1</PolicyName>
    <DefaultVersionId>vMFW10Z4EF4HL</DefaultVersionId>
    <PolicyId>ANVAP1OHCTVKCZR4TWB3F</PolicyId>
    <Path>/</Path>
    <Arn>arn:aws:iam::000000000000:policy/Policy1</Arn>
    <AttachmentCount>2</AttachmentCount>
    <CreateDate>2019-03-14T11:23:36.776Z</CreateDate>
    <UpdateDate>2019-03-14T11:23:36.776Z</UpdateDate>
    <Description>first test policy</Description>
   </member>
   <member>
    <PolicyName>Policy2</PolicyName>
    <DefaultVersionId>v0169a042bpk3</DefaultVersionId>
    <PolicyId>ANVAEQ3KKQOMWALATC1QT</PolicyId>
    <Path>/</Path>
    <Arn>arn:aws:iam::000000000000:policy/Policy2</Arn>
    <AttachmentCount>3</AttachmentCount>
    <CreateDate>2019-03-12T14:11:38.767Z</CreateDate>
    <UpdateDate>2019-03-12T14:11:38.767Z</UpdateDate>
    <Description>second test policy</Description>
   </member>
  </Policies>
  <IsTruncated>false</IsTruncated>
  <Marker></Marker>
 </ListPoliciesResult>
</ListPoliciesResponse>

Retrieves a list of all the policies. The list can be optionally filtered by specifying PathPrefix or OnlyAttached.

POST parameters

Parameter Description
Action must be set to ListPolicies
Version must be set to 2010-05-08
PathPrefix if specified, only the policies having a Path with the given prefix are returned
OnlyAttached if specified, only the policies attached to some user are returned

ListPolicyVersions

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=ListPolicyVersions
&PolicyArn=arn:aws:iam::000000000000:policy/TestPolicy
&Version=2010-05-08

Example response

<ListPolicyVersionsResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>s77xvbxffqqb</RequestId>
 </ResponseMetadata>
 <ListPolicyVersionsResult>
  <Versions>
   <member>
    <IsDefaultVersion>false</IsDefaultVersion>
    <VersionId>v1</VersionId>
    <CreateDate>2019-03-14T11:23:36.776Z</CreateDate>
   </member>
   <member>
    <IsDefaultVersion>true</IsDefaultVersion>
    <VersionId>v2Z0F1XI574I7</VersionId>
    <CreateDate>2019-03-14T11:37:20.523Z</CreateDate>
   </member>
  <IsTruncated>false</IsTruncated>
  <Marker></Marker>
 </ListPolicyVersionsResult>
</ListPolicyVersionsResponse>

Retrieves a list of versions of a specified policy

POST parameters

Parameter Description
Action must be set to ListPolicyVersions
Version must be set to 2010-05-08
PolicyArn ARN of the policy

ListUsers

List all users

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: [...]
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=ListUsers
&Version=2010-05-08

Example answer:

<ListUsersResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>mujpkfxe7slp</RequestId>
 </ResponseMetadata>
 <ListUsersResult>
  <Users>
   <member>
    <UserId>100000000042</UserId>
    <Path>/</Path>
    <UserName>testuser@example.com</UserName>
    <Arn>arn:aws:iam::000000000000:user/testuser@example.com</Arn>
    <CreateDate>2019-03-25T10:56:28.523Z</CreateDate>
    <PasswordLastUsed>2019-03-25T10:56:28.523Z</PasswordLastUsed>
   </member>
   <member>
    <UserId>100000000024</UserId>
    <Path></Path>
    <UserName>example@example.com</UserName>
    <Arn>arn:aws:iam::000000000000:user/example@example.com</Arn>
    <CreateDate>2019-03-25T10:56:28.523Z</CreateDate>
    <PasswordLastUsed>2019-03-25T10:56:28.523Z</PasswordLastUsed>
   </member>
  </Users>
  <IsTruncated>false</IsTruncated>
 </ListUsersResult>
</ListUsersResponse>

POST parameters

Parameter Description
Action must be set to ListUsers
Marker Pagination support. unused
MaxItems Pagination support. unused
PathPrefix user filtering. not supproted yet
Version must be set to 2010-05-08

SetDefaultPolicyVersion

Set the specified version of a policy as the default (active) version.

Note that this changes the currently active version for all attached entities.

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
User-Agent: [...]
Content-Type: application/x-www-form-urlencoded; charset=utf-8
X-Amz-Content-Sha256: [...]
X-Amz-Date: 20190325T103156Z
Authorization: [...]
Content-Length: [...]

Action=SetDefaultPolicyVersion
&PolicyArn=arn:aws:iam::123456789012:policy/policy-name
&VersionId=v42
&Version=2010-05-08

Example answer:

<SetDefaultPolicyResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>42bgut3b75zt</RequestId>
 </ResponseMetadata>
</SetDefaultPolicyResponse>

POST parameters

Parameter Description
Action must be set to SetDefaultPolicyVersion
PolicyArn ARN of the policy. example: arn:aws:iam::123456789012:policy/policy-name
VersionId version of the policy that you want as default
Version must be set to 2010-05-08

UpdateLoginProfile

Changes the password for the specified IAM user. For the current user use the "ChangePassword" API instead

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
User-Agent: [...]
Content-Type: application/x-www-form-urlencoded; charset=utf-8
X-Amz-Content-Sha256: [...]
X-Amz-Date: 20190325T103156Z
Authorization: [...]
Content-Length: [...]

Action=UpdateLoginProfile
&Password=Password22
&PasswordResetRequired=false
&UserName=testuser@example.com
&Version=2010-05-08

Example answer:

<UpdateLoginProfileResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">
 <ResponseMetadata>
  <RequestId>27bgut3b75zt</RequestId>
 </ResponseMetadata>
</UpdateLoginProfileResponse>

POST parameters

Parameter Description
Action must be set to UpdateLoginProfile
Password New password. Needs uppercase, lowercase, digits and at least 10 total characters
PasswordResetRequired true/false
UserName username to reset the password to
Version must be set to 2010-05-08

RSGetUserInfo

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
User-Agent: [...]
Content-Type: application/x-www-form-urlencoded; charset=utf-8
X-Amz-Content-Sha256: [...]
X-Amz-Date: 20190325T103156Z
Authorization: [...]
Content-Length: [...]

Action=RSGetUserInfo&
UserList.1=firstuser%40example.com&
UserList.2=seconduser%40example.com&
UserList.3=nonexistent&
Version=2010-05-08

Example answer:

[
 {
  "Id": "100000000780",
  "Name": "firstuser@example.com",
  "PwdMustChange": true,
  "Email": "firstuser@example.com",
  "Firstname": "First",
  "Lastname": "User",
  "Type": "admin",
  "CreatedOn": "2019-05-02T06:26:06.818Z",
  "LastAccess": "0001-01-01T00:00:00Z",
  "Path": "",
  "Root": "example"
 },
 {
  "Id": "100000000781",
  "Name": "seconduser@example.com",
  "PwdMustChange": true,
  "Email": "seconduser@example.com",
  "Firstname": "First",
  "Lastname": "User",
  "Type": "user",
  "CreatedOn": "2019-05-02T06:26:06.859Z",
  "LastAccess": "0001-01-01T00:00:00Z",
  "Path": "",
  "Root": "example"
 }
]

Retrieves information about a list of users. If no user is specified, information about the current user is returned. Only Root or Admin users can retrieve information about other users.

POST parameters

Parameter Description
Action must be set to RSGetUserInfo
Version must be set to 2010-05-08
UserList.$number username whose information should be retrieved

Response

The response is a json document containing, for each user:

RSSetUserInfo

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
User-Agent: [...]
Content-Type: application/x-www-form-urlencoded; charset=utf-8
X-Amz-Content-Sha256: [...]
X-Amz-Date: 20190325T103156Z
Authorization: [...]
Content-Length: [...]

Action=RSSetUserInfo&
Version=2010-05-08
Name=firstuser@example.com&
Firstname=John&
Lastname=Smith&
Type=user

Sets information for a given user

POST parameters

Parameter Description
Action must be set to RSSetUserInfo
Version must be set to 2010-05-08
Name user whose information should be set
Firstname first name to set
Lastname last name to set
Type type of user (root, admin, user)

Response

Returns a status code reflecting the outcome of the operation

RSGetPasswordResetToken (RSGetToken)

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
User-Agent: [...]
Content-Type: application/x-www-form-urlencoded; charset=utf-8
X-Amz-Content-Sha256: [...]
X-Amz-Date: 20190325T103156Z
Authorization: [...]
Content-Length: [...]

Action=RSGetToken&
Version=2010-05-08&
Type=pwd_reset&
UserName=firstuser%40example.com

Example response

{
 "Token": "AAAAAAAAAAAAAFMCAAAAAAAAAAAAAAAATMYFBVC2V3PJH3MDVOPV62XKJYRP7K2AUE6LCEV45ZQK4IA776W4F6A2OY2XYXJCHMJ5U4MJ2NXGQTK2XVBWVHQG43A3CC2PPX5NSKI="
}

Obtains a password reset token for a given user. Root and Admin users can obtain reset tokens for other users, in this case, the old password is immediately invalidated. Generated tokens are valid for 6 hours.

POST parameters

Parameter Description
Action must be set to RSGetToken
Version must be set to 2010-05-08
Type must be set to pwd_reset
UserName user whose password reset token should be obtained (defaults to the current user)

Response

Returns the requested password reset token in a json object

RSResetPassword

Example request (newlines added for clarity)

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
User-Agent: [...]
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: [...]

Action=RSResetPassword&
Version=2010-05-08&
Token=output.Token&
NewPassword=Password24

Resets a user's password using a password reset token. Note this call is not authenticated.

POST parameters

Parameter Description
Action must be set to RSGetToken
Version must be set to 2010-05-08
Token the password reset token
NewPassword new password to set

Response

Returns a status code reflecting the outcome of the operation

RSPrepareTFA

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
User-Agent: [...]
Content-Type: application/x-www-form-urlencoded; charset=utf-8
X-Amz-Content-Sha256: [...]
X-Amz-Date: [...]
Authorization: [...]
Content-Length: [...]

Action=RSPrepareTFA&Version=2010-05-08

Example response

{
 "secret": "RCULN35A63IMSO5UMW6FSUJIOTUOCDE7...",
 "qrCodeUrl": "data:image/png;base64,iVBORw0KGo..."
}

Prepares a 2FA secret for current user. After obtaining the secret, user can enable 2FA via RSEnableTFA API. The secret expires after 30 minutes.

POST parameters

Parameter Description
Action must be set to RSPrepareTFA
Version must be set to 2010-05-08

Response

Returns a secret key for generating time-based one-time passwords and a QR code image containing OTP URI with that secret.

RSEnableTFA

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
User-Agent: [...]
Content-Type: application/x-www-form-urlencoded; charset=utf-8
X-Amz-Content-Sha256: [...]
X-Amz-Date: [...]
Authorization: [...]
Content-Length: [...]

Action=RSEnableTFA&Version=2010-05-08&OTP=880631

Example response

{"recoveryCodes": ["52895ace", "f20f43ef", "f1ebaf4d", ...]}

Verifies the received OTP and enables 2FA for current user.

Parameter Description
Action must be set to RSEnableTFA
Version must be set to 2010-05-08
OTP 6-digit OTP derived from the secret from RSPrepareTFA

Response

Returns 10 recovery codes that can be used instead of OTP in case the user loses their 2FA device.

RSDisableTFA

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
User-Agent: [...]
Content-Type: application/x-www-form-urlencoded; charset=utf-8
X-Amz-Content-Sha256: [...]
X-Amz-Date: [...]
Authorization: [...]
Content-Length: [...]

Action=RSDisableTFA&Version=2010-05-08

Disables 2FA for current user.

Parameter Description
Action must be set to RSDisableTFA
Version must be set to 2010-05-08

RSCreateCustomer

Create a new customer under the current Reseller. This action should be performed using a Reseller account.

Parameter Description
CustomerName The name of the new customer (is enforced lowercase by the backend)
CustomerEmail The email of the new customer
AssumeRoleControl Specify who can control "AssumeRole" option for this customer: {"reseller", "customer", ""}
"reseller" => only the reseller can control it
"customer" => only the customer can decide if want to be managed or not
"" => if not set, "AssumeRole" is disabled
ReplicationEnforcement Specify if the customer can choose the replica location
Regions Is a list containing the available Regions for the given customer
RestrictServiceAccess Optional; if true, customer will not have access to any services initially. Services can be enabled through iam:RSSetCustomerServiceAccessLevel action

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: 182
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=RSCreateCustomer&Version=2010-05-08&Name=NewCorp&Email=admin%40newcorp.com&Password=Password22&AssumeRoleControl=customer&ReplicationEnforcement=false&ReplicationPolicy=%7B%7D

Example response

{"Ok":true,"Root":"rstor:newcorp","RootID":"100000000288"}

RSModifyCustomer

Modify an existing customer properties.

Parameter Description
CustomerName The name of the new customer
AssumeRoleEnabled Set if the AssumeRole is enabled or not
Status Set the status for the specified customer: "enabled", "disabled", "deleted"
ReplicationEnforcement Specify if the customer can choose the replica location
Regions Is a list containing the available Regions for the given customer

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: 133
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=RSModifyCustomer&Version=2010-05-08&CustomerName=newcorp&ReplicationEnforcement=false&ReplicationPolicy=null&Status=disabled

Example response

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Etag,X-Rstor-Size,X-Rstor-Replication-Status
Date: Mon, 14 Oct 2019 09:17:58 GMT
Content-Length: 0

RSListCustomer

Return a list of all Customers. Only a reseller account can perform this request.

Example request

POST /?Action=RSListCustomer&Version=2010-05-08
Host: iam.example.rstorcloud.io

Example response

[
  {
    "Name":"newcorp",
    "RootID":"100000000288",
    "Active":false,
    "CreatedOn":"2019-10-14T08:28:10.029Z",
    "SuspendedAt":"2019-10-14T09:17:58.647Z",
    "AssumeRoleControl":"customer",
    "AssumeRoleEnabled":false,
    "Regions":["DCA02", "SJC03"],
    "ReplicationEnforcement":false
  },
]

RSCustomerDetails

Return details about a specific customer. Only a reseller account can perform this request.

Example request

POST /?Action=RSCustomerDetails&Version=2010-05-08&CustomerName=newcorp
Host: iam.example.rstorcloud.io

Example response

{
  "Email":"admin@newcorp.com",
  "LastAccess":"2019-10-12T13:17:14.760Z",
  "AssumeRoleControl":"customer",
  "AssumeRoleEnabled":true,
  "Active":true,
  "NumBuckets":3,
  "NumFiles":12,
  "NumUsers":2,
  "NumAdminUsers":0,
  "NumAdminRoots":2,
  "UsedSpace":741987
}

RSAvailableRegions

Return a sorted list of regions available to the customer making the request and the value of the ReplicationEnforcement setting.

If ReplicationEnforcement is set to true, the customer is not able to create buckets with a different replication policy.

When called by a reseller, the Customer parameter allows retrieving the replication policy of a specific customer.

Example request

POST /?Action=RSAvailableRegions&Version=2010-05-08&Customer=newcorp
Host: iam.example.rstorcloud.io

Example response

{
  "Regions":["SJC03", "DCA02"],
  "ReplicationEnforcement": true,
}

RSListBillingData

Serves per-day statistics and billing data. The response consists of:

Entries are in reverse-chronological order.

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Type: application/x-www-form-urlencoded
Authorization: [...]

Action=RSListBillingData&Version=2010-05-08&From=2020-03-04T00%3A00%3A00.000Z&Till=2020-04-04T00%3A00%3A00.000Z

Example response

{
  "Stats": {
    "DCA02": [
      {
        "Date": "2020-04-03T00:00:00Z",
        "UploadBytes": 28398312,
        "DownloadBytes": 56709864,
        "DeleteBytes": 28398312
      },
      // ...
    ],
    // ...
  },
  "UsedSpace": [
    {
      "Date": "2020-04-03T00:00:00Z",
      "UsedSpace": 6485663588183,
      "GhostSpace": 402901552935
    },
    // ...
  ],
  "ObjectCount": [
    {
      "Date": "2020-04-03T00:00:00Z",
      "ObjectCount": 18499
    },
    // ...
  ]
}

POST parameters

Parameter Description
Action must be set to RSListBillingData
Version must be set to 2010-05-08
From ISO-8601-formatted UTC date of the first requested day
Till ISO-8601-formatted UTC date of the last requested day

RSLiveBilling

Serves recent billing metrics for the last hour. Entries for the last two minutes are omitted in order to ensure the returned data is complete.

The API returns stats aggregated by one-minute windows, ordered from the most recent to the oldest. In case there is no activity in a time window, the corresponding entry is omitted.

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Type: application/x-www-form-urlencoded
Authorization: [...]

Action=RSLiveBilling&Version=2010-05-08

Example response

[
 {
  "date": "2020-04-23T12:35:00Z",
  "uploadedBytes": 24623534,
  "uploadedObjects": 3,
  "deletedBytes": 0,
  "deletedObjects": 0
 },
 {
  "date": "2020-04-23T12:34:00Z",
  "uploadedBytes": 24623534,
  "uploadedObjects": 3,
  "deletedBytes": 0,
  "deletedObjects": 0
 },
 {
  "date": "2020-04-23T12:29:00Z",
  "uploadedBytes": 2786761,
  "uploadedObjects": 12,
  "deletedBytes": 0,
  "deletedObjects": 0
 }
]

POST parameters

Parameter Description
Action must be set to RSLiveBilling
Version must be set to 2010-05-08

RSWhitelistAddRule

Add a new whitelist rule to the current list of whitelist subnets.

Property Value
Permission required ADMIN
Service IAM
UrlPath /api/whitelist/RSWhitelistAddRule
Method PUT
Content-Type json

Request body

{
  "root": <root_name>, // mandatory
  "subNet": <subnet>, // mandatory
  "regions": ["DCA02","SCJ03","DEN02","LON01"], // optional (if empty apply to all regions)
  "notes": <some notes for the reseller>, // optional
  "ttl": <time to live in days after the approval>, // optional
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 27 Apr 2020 14:16:59 GMT
Content-Length: 109

{"ok":true,"ruleId":"c205e1b6-8891-11ea-968c-14cc2006610b","insertedAt":"2020-04-27T16:16:59.50222599+02:00"}

RSWhitelistDeleteRule

Remove a rule from the current subnet whitelist.

Property Value
Permission required RESELLER if the Rule is Active (was approved), ADMIN or RESELLER if the rule is still pending
Service IAM
UrlPath /api/whitelist/RSWhitelistDeleteRule
Method DELETE
Content-Type json

Request body

{
  "root": <root_name>, // mandatory
  "ruleId": <rule identity number>, // mandatory
}

Response

Simple http response + json body { "ok": true/false, "errorDesc": "optional error description" }

RSWhitelistApproveRule

Approve a rule in Pending state.

Property Value
Permission required RESELLER
Service IAM
UrlPath /api/whitelist/RSWhitelistApproveRule
Method POST
Content-Type json

Request body

{
  "root": <root_name>, // mandatory
  "ruleId": <rule identity number>, // mandatory
  "notes": <some notes to report> // optional
}

Response

{
  "ok": <true,false>,
  "errorDesc": "", // optional
  "ruleId": <rule identity number>,
  "status": <current_status>,
  "updatedAt": <update ts>
}

RSWhitelistRejectRule

Reject a rule in Pending state.

Property Value
Permission required RESELLER
Service IAM
UrlPath /api/whitelist/RSWhitelistRejectRule
Method POST
Content-Type json

Request body

{
  "root": <root_name>, // mandatory
  "ruleId": <rule identity number>, // mandatory
  "notes": <some notes to report> // optional
}

Response

{
  "ok": <true,false>,
  "errorDesc": "", // optional
  "ruleId": <rule identity number>,
  "status": <current_status>,
  "updatedAt": <update ts>
}

RSWhitelistListRules

List all rules (subnets).

Property Value
Permission required RESELLER
Service IAM
UrlPath /api/whitelist/RSWhitelistListRules
Method GET

Get Parameters

Param Desc
root root name
offset 0 (used for pagination, not yet implemented)
limit 0 (used for pagination, not yet implemented)

Responses

{
  "ok": <true,false>,
  "partial": <true,false>, // if true means that only some rules are returned
  "rules": [
    "ruleId": <rule identifier>, // always present
    "insertedAt": <timestamp>, // always present
    "updatedAt": <timestamp>, // always present
    "subNet": <subnet>, // always present
    "status": <Active,Pending,Rejected,Suspended>, // always present
    "regions": ["DCA02","SCJ03","DEN02","LON01"], // optional (if empty apply to all regions)
    "notes": <rule notes>, // optional
  ],
  "errorDesc": "optional error description"
}

RSWhitelistStats

Upcoming.

RSSetCustomerServiceAccessLevel

Configures a service for a customer with RestrictServiceAccess enabled

Property Value
CustomerName Name of the customer to manage
Service Name of the service to manage, must be one of:
space, transporter, insights, protect
Enabled true / false to enable / disable the service
ExpirationDate This setting has no effect if Enabled is false
If set, the service will be available until the specified date
If omitted, the service will be available indefinitely

Example request

POST / HTTP/1.1
Host: iam.example.rstorcloud.io
Content-Length: 86
Content-Type: application/x-www-form-urlencoded
Authorization: [...]
X-Amz-Date: [...]

Action=RSSetCustomerServiceAccessLevel&Service=transporter&AccessLevel=enabled

Space

The Space endpoint (https://s3.example.rstorcloud.io) allows to perform operations on files and buckets. Requests to this endpoint must be signed with AWS Signature V4 or V2, specifying s3 as the service. Note that only path-style requests are supported.

The following api calls are supported:

Bucket list (GET Service)

Example response

<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 <Buckets>
  <Bucket>
   <Name>private-bucket</Name>
   <CreationDate>2019-04-24T17:20:01.997Z</CreationDate>
  </Bucket>
  <Bucket>
   <Name>public-bucket</Name>
   <CreationDate>2019-04-24T17:18:59.552Z</CreationDate>
  </Bucket>
 </Buckets>
 <Owner>
  <ID>100000000013</ID>
  <DisplayName>example</DisplayName>
 </Owner>
</ListAllMyBucketsResult>

GET /

Returns a list of all the buckets the current user has access to

Create Bucket (PUT Bucket)

Example response

HTTP/1.1 200 OK
Date: Mon, 22 Jul 2019 09:48:09 GMT
Content-Length: 0

PUT /mybucket

Creates a new bucket mybucket. Anonymous requests are not allowed to create buckets. The additional replication-policy parameter can be used to specify the list of regions where to replicate the bucket. If not specified, buckets are replicated in every region.

PUT Parameters

The following optional PUT parameters can be specified:

Form Parameter Description
replication-policy Specify a comma separated list of regions identifiers (Eg. DCA02,DEN02,SJC03)

Header parameters

Headers Description
x-amz-bucket-object-lock-enabled If set to true create the bucket in locking mode and activate the versioning
x-amz-grant-read
x-amz-grant-write

Response

Returns 200 in case of success, 400 in case the bucket name is not valid, or 409 conflict error when you try to create a bucket which is already present.

Delete Bucket

Example response

HTTP/1.1 200 OK
Date: Mon, 22 Jul 2019 09:48:09 GMT
Content-Length: 0

DELETE /mybucket

Deletes the bucket mybucket. Anonymous requests are not allowed to delete buckets.

Response

Returns 200 in case of success, 404 in case the bucket does not exists, or 409 conflict error in case bucket is not empty.

List Objects (GET Bucket)

Example request

GET /abc-bucket/?list-type=2&delimiter=/&max-keys=300&prefix=test-a/

Example response (in ListObjectsV2 format)

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>abc-bucket</Name>
    <Prefix></Prefix>
    <ContinuationToken></ContinuationToken>
    <MaxKeys>300</MaxKeys>
    <KeyCount>4</KeyCount>
    <Delimiter>/</Delimiter>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>files.zip</Key>
        <LastModified>2019-02-23T12:41:11.000Z</LastModified>
        <Size>25617859</Size>
        <Owner>
            <ID>0</ID>
        </Owner>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <CommonPrefixes>
        <Prefix>example-directory/</Prefix>
    </CommonPrefixes>
    <CommonPrefixes>
        <Prefix>other-directory/</Prefix>
    </CommonPrefixes>
</ListBucketResult>

GET / or GET /?list-type=2

GET Parameters

The following optional GET parameters can be specified:

Parameter Description
list-type (when set to "2", specifies that the ListObjectsV2 format should be used)
max-keys specifies a maximum number of keys to be returned. Defaults to the maximum value of 1000
prefix filters the returned keys by prefix. Can be used to specify a directory
continuation-token pagination token, which can be set to the NextContinuationToken element of the previous result page (if list-type is not set, "marker" should be used instead)
fetch-owner returns owner field with each key in the result
start-after Space will start listing after this specified key. It can be any key in the bucket.

Response

On success, an XML document is returned, containing the first max-keys items of the requested listing. When the listing contains more than max-keys items, then the response contains the elements <IsTruncated>true</IsTruncated>, and a pagination token (either <NextContinuationToken> if list-type=2, or NextMarker) which can be used to retrieve the next page.

If the prefix parameter is specified and has a trailing slash, the contents of the listing are the files and folder in that directory. If the prefix parameter does not contain a slash, it is used to filter the contents of the parent folder. The listing is sorted in lexicographical order.

List Objects (Versioned Bucket)

GET /abc-bucket/?prefix=myprefix&versions=

Example with aws client:

 aws s3api list-object-versions --bucket examplebucket --prefix myprefix

Example response:

{
    "DeleteMarkers": [
        {
            "Owner": {
                "ID": "100000000001"
            },
            "IsLatest": true,
            "VersionId": "itdou5ddl1j558z4",
            "Key": "doc2.jpg",
            "LastModified": "2019-07-18T09:58:58.1718141Z"
        }
    ],
    "Versions": [
        {
            "LastModified": "2019-07-18T09:58:42.7619115Z",
            "VersionId": "s343opv4r1hv2vx3",
            "ETag": "\"324f6cbcfdf2420dd63890234a9f2f14\"",
            "StorageClass": "STANDARD",
            "Key": "doc2.jpg",
            "Owner": {
                "ID": "100000000001"
            },
            "IsLatest": true,
            "Size": 149951
        },
        {
            "LastModified": "2019-07-18T09:58:28.3141363Z",
            "VersionId": "scmsdt1jl0395uby",
            "ETag": "\"324f6cbcfdf2420dd63890234a9f2f14\"",
            "StorageClass": "STANDARD",
            "Key": "doc1.jpg",
            "Owner": {
                "ID": "100000000001"
            },
            "IsLatest": true,
            "Size": 149951
        },
        {
            "LastModified": "2019-07-18T09:58:12.0506257Z",
            "VersionId": "536znyl9hzlgczh3",
            "ETag": "\"f3658d735ac33d68a23909b1d2583421\"",
            "StorageClass": "STANDARD",
            "Key": "doc3.jpg",
            "Owner": {
                "ID": "100000000001"
            },
            "IsLatest": true,
            "Size": 578504
        }
    ]
}

Is similar to List Object on a non-versioned bucket but return all the versions for a specified prefix including all elements markerd as DeleteMarker. A delete marker is a marker that points to a specific object in the bucket and indicates that this object is deleted. Every deleted object has a specific VersionId.

Response

On success, an XML document is returned, containing the first max-keys items of the requested listing. When the listing contains more than max-keys items, then the response contains the elements <IsTruncated>true</IsTruncated>. Every versions for the specified prefix is returned. The latest version is marked using the element <IsLatest>true</IsLatest>.

HEAD Bucket

Example response

HTTP/2.0 200 OK
Connection: close
Date: Tue, 30 Apr 2019 09:24:41 GMT
X-Rstor-Size: 35342254

HEAD /<bucket>

Returns 200 if the bucket exists, 404 otherwise. If available, the X-Rstor-Size header is returned, reporting the current size of the bucket in bytes.

Delete Multiple Objects

Example request body

<Delete>
  <Object>
    <Key>example1</Key>
  </Object>
  <Object>
    <Key>example2</Key>
  </Object>
</Delete>

Example response

<?xml version="1.0" encoding="UTF-8"?>
<DeleteResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Deleted>
    <Key>example1</Key>
  </Deleted>
  <Error>
    <Key>example2</Key>
    <Code>AccessDenied</Code>
    <Message>Access Denied</Message>
  </Error>
</DeleteResult>

POST /<bucket>?delete

The request body must contain a XML document in the format specified by the example, with a list of keys to delete (up to 1000).

Response

The response is a XML document, containing, for each key, either a <Deleted> element or an <Error> element, according to the result of the operation.

DELETE Object

DELETE /<bucket>/<object>

Deletes the requested object or empty directory. Deleting a non-empty directory causes an error. Deleting an object that does not exist returns no error. HTTP Response code of 204 is normal and indicates that the object was successfully deleted.

In case of a versioned bucket is possible to:

If the versioning, in a specific bucket, is in Suspend State then the Delete operation can remove the object only if his version ID is null. In any case it add a new DeleteMarker with versionId set to null.

To remove a specific versionId: DELETE /<bucket>/<object>?versionId=<version_id>

GET Object

Example response

HTTP/1.1 200 OK
content-length: 25617859
content-type: binary/octet-stream
date: Mon, 25 Feb 2019 10:49:59 GMT
etag: "918a4f4a76bfa69c193fd4365bc12622"
last-modified: Mon, 25 Feb 2019 10:49:59 GMT
X-Rstor-Replication-Status: DEN02,SJC03

Object contents

GET /<bucket>/<object> or GET /<bucket>/<object>?versionId=<versionId>

Retrieve an object in a bucket. In case the bucket has versioning enabled we can specify the versionId. If the current version of the object is a delete marker, the object was deleted, the flag x-amz-delete-marker: true is in included in the response. The API provides the replication status in the X-Rstor-Replication-Status header as a list of regions.

Header parameters

Header Description
Range specifies a byte range to be retrieved, in the format bytes:<start>-<end>
x-amz-server-side​-encryption​-customer-algorithm SSE-C algorithm (supported: AES256)
x-amz-server-side​-encryption​-customer-key SSE-C base64-encoded decryption key
x-amz-server-side​-encryption​-customer-key-MD5 SSE-C base64-encoded key hash (MD5)
x-rstor-replication-status if specified, the replication status is returned back as a list of regions
x-amz-checksum-mode if specified, the checksum mode will be returned on headers, valid value: ENABLED

Query parameters

The following query parameters can be used to set or override the corresponding headers in the response the server sends back.

Parameter Description
response-content-type sets the "Content-Type" header on the response
response-content-language sets the "Content-Language" header on the response
response-expires sets the "Expires" header on the response
response-cache-control sets the "Cache-Control" header on the response
response-content-disposition sets the "Cache-Disposition" header on the response
response-content-encoding sets the "Content-Encoding" header on the response

Response

On success, a status code of 200 is returned. An error code is returned otherwise. In case this operation is performed in a bucket that has the versioning enabled the corresponding VersionId is returned. Moreover, in case the bucket has one or more lifecycle Expiration rules that apply to newly created object, the corresponding Expiration is returned. Finally, if object was uploaded with SSE-S3 or SS3-C encryption, ServerSideEncryption is returned.

HEAD Object

Example Response

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Length: 57301
Content-Type: text/plain
ETag: "18e20a76b174f184fad0febced4dbc51"
Last-Modified: Fri, 19 Jul 2019 17:14:35 GMT
X-Rstor-Replication-Status: DEN02,SJC03
Date: Mon, 22 Jul 2019 10:45:57 GMT

HEAD /<bucket>/<object>

Allows retrieving metadata about a given object. It supports the same parameters and returns the same response as the "GET Object" call, but with an empty body. If the x-rstor-replication-status: true header is specified in the request, the API provides the replication status in the X-Rstor-Replication-Status header as a list of regions. This request support x-amz-checksum-mode: ENABLED to retrieve checksum stored if using custom checksum algorithm (x-amz-checksum-algorithm or x-amz-checksum-*).

PUT Object

PUT /<bucket>/<object>

Sets the contents of an object to the contents of the request's body, creating the object if it does not exists. If the x-amz-copy-source header is specified, the object is copied from the one specified in the header, and the body of the PUT request is ignored.

Object keys must be valid UTF8 strings and must not end with a trailing slash. However, a request with an empty body can specify a key with a trailing slash, in this case an empty directory is created.

Header parameters

The PutObject API supports the following optional headers

Header Description
Content-Md5 The MD5 hash of the content. If present, it is checked as an additional guarantee that the object was correctly received
x-amz-copy-source The object specified in the header is copied to the target key
x-amz-tagging The tag-set to assign to the uploaded object, formatted as a query string (for example, "Key1=Value1")
x-amz-tagging-directive Specifies whether the object tag-set are copied from the source object or replaced with tag-set provided in the request. Valid Values: COPY or REPLACE
x-amz-server-side-encryption SSE-S3 Algorithm (supported: AES256)
x-amz-server-side​-encryption​-customer-algorithm SSE-C algorithm (supported: AES256)
x-amz-server-side​-encryption​-customer-key SSE-C base64-encoded encryption key
x-amz-server-side​-encryption​-customer-key-MD5 SSE-C base64-encoded encryption key hash (MD5)
x-amz-copy-source-server-side​-encryption​-customer-algorithm SSE-C algorithm of the source object (supported: AES256)
x-amz-copy-source-server-side​-encryption​-customer-key SSE-C base64-encoded decryption key of the source object
x-amz-copy-source-server-side​-encryption​-customer-key-MD5 SSE-C base64-encoded decryption key hash (MD5) of the source object
x-amz-checksum-algorithm or x-amz-sdk-checksum-algorithm Custom checksum algorithm (valid values: CRC32, CRC32C, SHA1, SHA256), stored checksum can be retrieved by calling GetObject
x-amz-checksum optional base64-encoded checksum for custom checksum algorithm
x-amz-trailer optional compatibility header, may contain value: x-amz-checksum-crc32, x-amz-checksum-crc32c, x-amz-checksum-sha1, or x-amz-checksum-sha256
x-amz-checksum-crc32 CRC32 checksum of the object (base64-encoded)
x-amz-checksum-crc32c CRC32C checksum of the object (base64-encoded)
x-amz-checksum-sha1 SHA1 checksum of the object (base64-encoded)
x-amz-checksum-sha256 SHA256 checksum of the object (base64-encoded)

If the checksum is calculated on the client side, it should be sent to the server in the x-amz-checksum-crc32, x-amz-checksum-crc32c, x-amz-checksum-sha1, or x-amz-checksum-sha256 headers or a combination of x-amz-checksum and x-amz-checksum-algorithm or x-amz-sdk-checksum-algorithm. The server will verify the checksum, and will return an error if the checksums do not match.

Example valid base64-encoded checksum values for "Hello world\n123\n" without quotes

If specified, the value of the following headers will be stored alongside the object, and then returned on the HeadObject or GetObject APIs:

Custom metadata can be specified by means of headers with the x-amz-meta- prefix, up to a total of 2KB of data (counting both header names and values).

Response

On success, a status code of 200 is returned. An error code is returned otherwise. In case this operation is performed in a bucket that has the versioning enabled the corresponding VersionId is returned. Moreover, in case the bucket has one or more lifecycle expiration rules that apply to newly created object, the corresponding Expiration is returned. Finally, if object was uploaded with SSE-S3 or SS3-C encryption, ServerSideEncryption is returned.

Example on a NON-versioned bucket:

{
  "ETag": "\"324f6cbcfdf2420dd63890234a9f2f14\""
}

Example on a versioned bucket:

{
  "VersionId": "khd1pmwdgewhlnd2",
  "ETag": "\"324f6cbcfdf2420dd63890234a9f2f14\""
}

Example how to do upload and download using AWS-SDK-Go-v2

package main

import (
    "context"
    _ "embed"
    "encoding/json"
    "strings"
    "log"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/aws/middleware"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/aws-sdk-go-v2/service/s3/types"
    "github.com/aws/smithy-go/transport/http"
)

// the secret file will be embedded on compile time
// the file should contain something like this:
/* {
     "url":"https://BUCKET.s3.RESELLER.rstorcloud.io", 
     "accessKey": "RSTOR...", 
     "secretKey": "..."
   }
*/
// REGION: sjc03, dca02, den02, lon01, lon02, toy01, osa01
// BUCKET: bucket name

//go:embed secret.json
var secret []byte

// config.json will be deserialized to this struct
type Cfg struct {
    Url       string `json:"url"`
    AccessKey string `json:"accessKey"`
    SecretKey string `json:"secretKey"`
}

// helper function for exit early CLI and print stack trace
// do not use for long-running service
func panicIf(err error, str string) {
    if err != nil {
        log.Println(str)
        panic(err)
    }
}

func main() {
    // load secrets from configuration
    var jsonCfg Cfg
    err := json.Unmarshal(secret, &jsonCfg)
    panicIf(err, `secret.json parsing failed`)

    // file name to upload
    key := aws.String(`FILENAME`)
    // example content of the file to be uploaded
    const helloWorld = "Hello world\n123\n"

    // retrieve bucket from config
    dotPos := strings.Index(jsonCfg.Url,".")
    bucketName := jsonCfg.Url[8:dotPos] // "https://" have length of 8
    log.Println(`bucket name:`, bucketName)
    bucket := aws.String(bucketName)

    usingPF := strings.Contains(jsonCfg.Url, `rstorcloud.io`) ||
        strings.Contains(jsonCfg.Url, `packetfabric-storage.com`)

    // connection configuration
    ctx := context.Background()
    opts := [](func(options *config.LoadOptions) error){}
    opts = append(opts, config.WithRegion(region))
    cred := credentials.NewStaticCredentialsProvider(jsonCfg.AccessKey, jsonCfg.SecretKey, "")
    opts = append(opts, config.WithCredentialsProvider(cred))
    var awsCfg aws.Config
    if usingPF { // override AWS default URL
        resolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...any) (aws.Endpoint, error) {
            return aws.Endpoint{
                SigningRegion:     region,
                URL:               jsonCfg.Url,
                HostnameImmutable: true,
            }, nil
        })
        opts = append(opts, config.WithEndpointResolverWithOptions(resolver))
    }
    awsCfg, err = config.LoadDefaultConfig(ctx, opts...)
    panicIf(err, `failed config.LoadDefaultConfig`)

    // create s3 client
    s3Client := s3.NewFromConfig(awsCfg)

    // create bucket
    _, err := s3Client.CreateBucket(ctx, &s3.CreateBucketInput{
        Bucket: bucket,
    })
    if err != nil {
        log.Printf(`s3Client.CreateBucket failed %s: %s`, *bucket, err)
    } else {
        log.Printf(`bucket %v created`, *bucket)
    }

    {
        log.Println(`PutObject start`)
        out, err := s3Client.PutObject(ctx, &s3.PutObjectInput{
            Bucket:            bucket,
            Key:               key,
            Body:              strings.NewReader(helloWorld),
            // enable one of these to do checksum verification:
            //ChecksumCRC32: aws.String(`uWvPlg==`),
            //ChecksumCRC32C: aws.String(`Cy8XOQ==`),
            //ChecksumSHA1: aws.String(`LupGMeUw441P/33BhJlOZVSBpVg=`),
            //ChecksumSHA256: aws.String(`uzbBRoYAgN7yiuoYiZFk6kfOPcFad8E8uxFLXfuKVsA=`),
        })
        panicIf(err, `failed s3Client.PutObject`)
        log.Println(`PutObject success`)
        log.Println(middleware.GetRawResponse(out.ResultMetadata).(*http.Response).Header)
    }

    {
        log.Println(`GetObject start`)
        out, err := s3Client.GetObject(ctx, &s3.GetObjectInput{
            Bucket:       bucket,
            Key:          key,
            // checksum always returned by default
            //ChecksumMode: types.ChecksumModeEnabled, // X-Amz-Checksum-Mode
        })
        panicIf(err, `failed s3Client.GetObject`)
        log.Println(`GetObject success`)
        log.Println(middleware.GetRawResponse(out.ResultMetadata).(*http.Response).Header)
    }
}

Initiate Multipart Upload

Example response

<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>bucketA</Bucket>
  <Key>objectKey</Key>
  <UploadId>ifWDmLwLgAR8QDN/tg67DObvjR4=</UploadId>
</InitiateMultipartUploadResult>

POST /<bucket>/<object>?uploads

Initiates a new multipart upload, returning a new upload ID.

Post parameters

No request parameters used

Header parameters

The following optional headers are supported:

Header Description
x-amz-tagging The tag-set to assign to the uploaded object, formatted as a query string (for example, "Key1=Value1")
x-amz-server-side-encryption SSE-S3 Algorithm (supported: AES256)
x-amz-server-side​-encryption​-customer-algorithm SSE-C algorithm (supported: AES256)
x-amz-server-side​-encryption​-customer-key SSE-C base64-encoded encryption key
x-amz-server-side​-encryption​-customer-key-MD5 SSE-C base64-encoded encryption key hash (MD5)
x-amz-checksum-algorithm or x-amz-sdk-checksum-algorithm Custom checksum algorithm for the uploaded part, valid values: CRC32, CRC32C, SHA1, SHA256)

Additionally the following metadata headers are supported, and will be stored together with the object once the upload is completed.

Example how to do upload multipart using AWS-SDK-Go-v2


// connection part see PutObject example above

    out, err := s3Client.CreateMultipartUpload(ctx, &s3.CreateMultipartUploadInput{
        Bucket:            bucket,
        Key:               key,
        //ChecksumAlgorithm: types.ChecksumAlgorithmCRC32,
    })
    panicIf(err, `failed s3Client.CreateMultipartUpload`)

Upload Part

Example response

HTTP/1.0 200 OK
date: Mon, 25 Feb 2019 12:10:46 GMT
etag: "a2f4f30ec726440bcc748981e82f43fc"

PUT /<bucket>/<object>?partNumber=<partNumber>&uploadID=<uploadID>

The request is analogous to "Put Object", but specifies two additional query parameters: partNumber and uploadId. The parameters object and uploadID must be equal respectively to the ones provided and returned in the "Initiate Multipart Upload" call. The partNumber will be used to reassemble the uploaded parts.

Header parameters

The UploadPart operation supports the following optional headers

Header Description
Content-Md5 The MD5 hash of the content. If present, it is checked as an additional guarantee that the object was correctly received
x-amz-copy-source The object specified in the header is copied to the target partNumber for specified uploadId multipart
x-amz-server-side​-encryption​-customer-algorithm SSE-C algorithm (supported: AES256)
x-amz-server-side​-encryption​-customer-key SSE-C base64-encoded encryption key
x-amz-server-side​-encryption​-customer-key-MD5 SSE-C base64-encoded encryption key hash (MD5)
x-amz-copy-source-server-side​-encryption​-customer-algorithm SSE-C algorithm of the source object (supported: AES256)
x-amz-copy-source-server-side​-encryption​-customer-key SSE-C base64-encoded decryption key of the source object
x-amz-copy-source-server-side​-encryption​-customer-key-MD5 SSE-C base64-encoded decryption key hash (MD5) of the source object
x-amz-checksum-algorithm or x-amz-sdk-checksum-algorithm Custom checksum algorithm for the uploaded part, valid values: CRC32, CRC32C, SHA1, SHA256)
x-amz-checksum optional base64-encoded checksum for custom checksum-algorithm
x-amz-trailer optional compatibility header, may contain value: x-amz-checksum-crc32, x-amz-checksum-crc32c, x-amz-checksum-sha1, or x-amz-checksum-sha256
x-amz-checksum-crc32 CRC32 checksum of the object (base64-encoded)
x-amz-checksum-crc32c CRC32C checksum of the object (base64-encoded)
x-amz-checksum-sha1 SHA1 checksum of the object (base64-encoded)
x-amz-checksum-sha256 SHA256 checksum of the object (base64-encoded)

If checksum-algorithm supplied, it would behave the same as Put Object. Optionally if checksum calculation done on client side, x-amz-checksum-crc32 or x-amz-cheecksum-crc32c, x-amz-checksum-sha1 or x-amz-checksum-sha256 can be sent, server will verify the checksum and return error if it does not match. If x-amz-checksum-* not set, server will calculate the checksum that can be used optionally on Complete Multiple Upload.

Response

The response has an empty body, and specifies a status code (reflecting the outcome of the operation), and the ETag of the uploaded object as a header. The returned ETag must be noted, as it is required in the Complete Multipart Upload request.

Complete Multipart Upload

Example request

<CompleteMultipartUpload xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Part>
        <ETag>"a2f4f30ec726440bcc748981e82f43fc"</ETag>
        <PartNumber>1</PartNumber>
    </Part>
    <Part>
        <ETag>"d12b6b5a7f8f850c39f32a96e36b5f69"</ETag>
        <PartNumber>2</PartNumber>
    </Part>
    <Part>
        <ETag>"e882613760157a24939f87a210043d47"</ETag>
        <PartNumber>3</PartNumber>
    </Part>
</CompleteMultipartUpload>

On each part, there's optional ChecksumCRC32, ChecksumCRC32C, ChecksumSHA1, ChecksumSHA256 fields, for example: <ChecksumCRC32>abcdef==</ChecksumCRC32>, which is used to verify the integrity of the concatenated checksum of the uploaded parts, this should match with the custom checksum-algorithm (x-amz-checksum-algorithm or x-amz-sdk-checksum-algorithm) that started in Initiate Multipart Upload phase. PartNumber must be in sequential order or the server will return an error.

Example response

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Location>http://s3.amazonaws.com/abc-bucket/gparted-live-0.33.0-1-amd64.iso</Location>
    <Bucket>abc-bucket</Bucket>
    <Key>gparted-live-0.33.0-1-amd64.iso</Key>
    <ETag>&quot;7b2ca2b72d990a59a6ac992e5a7f910c-9&quot;</ETag>
</CompleteMultipartUploadResult>

Example response (in case of error)

<Error>
  <Code>InternalError</Code>
  <Message>We encountered an internal error. Please try again.</Message>
</Error>

POST /<bucket/<object>?uploadId=<uploadId>

Completes a multipart upload, assembling the parts in ascending partNumber order.

The request body is an XML document listing the parts to assemble, each with the partNumber and ETag respectively in the "Upload Part" request and response.

Response

The response is an XML document, which specifies the outcome of the upload, and either the reassembled file key and ETag, or an error. Moreover, in case the bucket has one or more lifecycle Expiration rules that apply to newly created object, the corresponding Expiration is returned.

Abort Multipart Upload

DELETE /<bucket>/<object>?uploadId=<uploadId>

Removes a multipart upload and all the parts that have been uploaded up to that moment.

Response

Returns a status code reflecting the outcome of the operation

List Multipart Uploads

Example response

<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 <Bucket>examplebucket</Bucket>
 <Upload>
  <Key>testMultipartTest.txt</Key>
  <UploadId>sNyryKj9Jzd5T1gdFpotuiRRcAASIz4nBNa24NSOYgHZYdl5aN</UploadId>
  <Initiator>
   <ID>99woic3r@example.com</ID>
   <DisplayName>99woic3r@example.com</DisplayName>
  </Initiator>
  <Owner>
   <ID>100000000001</ID>
   <DisplayName>example</DisplayName>
  </Owner>
  <StorageClass>STANDARD</StorageClass>
  <Initiated>2019-04-29T13:35:48.420Z</Initiated>
 </Upload>
</ListMultipartUploadsResult>

GET /<bucket>?uploads

Lists the multipart uploads for a given bucket that have been initialized but not yet completed or aborted.

List Multipart Parts

Example response

 <ListPartsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
 <Bucket>examplebucket</Bucket>
 <IsTruncated>false</IsTruncated>
 <Part>
  <ETag>&#34;3e7bb4a9c59d736603a0b764f1696b7d&#34;</ETag>
  <PartNumber>1</PartNumber>
  <LastModified>2019-04-29T13:35:48.425Z</LastModified>
  <Size>5</Size>
 </Part>
 <Part>
  <ETag>&#34;3e7bb4a9c59d736603a0b764f1696b7d&#34;</ETag>
  <PartNumber>2</PartNumber>
  <LastModified>2019-04-29T13:35:48.430Z</LastModified>
  <Size>5</Size>
 </Part>
 <Key>testMultipartTest.txt</Key>
 <UploadId>sNyryKj9Jzd5T1gdFpotuiRRcAASIz4nBNa24NSOYgHZYdl5aN</UploadId>
 <Initiator>
  <ID>99woic3r@example.com</ID>
  <DisplayName>99woic3r@example.com</DisplayName>
 </Initiator>
 <Owner>
  <ID>100000000001</ID>
  <DisplayName>example</DisplayName>
 </Owner>
 <StorageClass>STANDARD</StorageClass>
 <Initiated>2019-04-29T13:35:48.420Z</Initiated>
</ListPartsResult>

GET /<bucket>/<object>?uploadID=<uploadId>

Lists the uploaded parts for a given multipart upload, with their ETag, part number, upload id, size and last modified time. It does not support pagination-related parameters: max-parts and NextPartNumberMarker.

Put Bucket Policy

Example request body

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": ["s3:GetBucketLocation"],
      "Effect": "Allow",
      "Principal": { "AWS": ["*"] },
      "Resource": ["arn:aws:s3:::abc-bucket"],
      "Sid": ""
    },
    {
      "Action": ["s3:GetObject"],
      "Effect": "Allow",
      "Principal": { "AWS": ["*"] },
      "Resource": ["arn:aws:s3:::abc-bucket/*"],
      "Sid": ""
    }
  ]
}

PUT /<bucket>?policy

Sets the access policy for a given bucket. Currently, we only support using bucket policies to make a bucket publicly accessible.

In the example, a policy allowing anonymous GetObject requests is assigned to the bucket abc-bucket.

Response

Returns a status code indicating whether the operation was successful.

Get Bucket Policy

GET /<bucket>?policy

Response

Returns the current bucket policy. If no bucket policy is set, a 404 error is returned.

Delete Bucket Policy

DELETE /<bucket>?policy

Removes the access policy set for a given bucket.

Response

Returns a status code indicating whether the operation was successful.

Put Bucket Versioning

Example with aws client to Enable:

aws s3api put-bucket-versioning --bucket test --versioning-configuration "Status=Enabled"

Example with aws client to Suspend:

aws s3api put-bucket-versioning --bucket test --versioning-configuration "Status=Suspended"

Example xml request:

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Status>[Enabled | Suspended]</Status>
</VersioningConfiguration>

PUT /<bucket>/?versioning

Enable versioning on the specified bucket.

GET Bucket Versioning

Example with aws client:

aws s3api get-bucket-versioning --bucket test

GET /<bucket>/?versioning

Return the status of versioning for the given bucket

Response

{
    "Status": "Enabled"
}

The possible value for status are:

RSGetBucketInfo

Example request

GET /examplebucket?rs-info= HTTP/1.1
Host: 127.0.0.1:44355
User-Agent: Go-http-client/1.1
Authorization: AWS4-HMAC-SHA256 Credential=RSTOR1ARO9Y8B0272GA5LAERGU/20190722/any/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=000e8c03d6afe31c96bb616a8f67e29b7cf1308ab196adb2fa757d27750b66aa
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Amz-Date: 20190722T110035Z
Accept-Encoding: gzip

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 22 Jul 2019 11:00:35 GMT
Content-Length: 73

{
  "bucketSize": 57300,
  "replicationPolicy": [
    "DEN02",
    "SJC03"
  ],
  "isPublic": false
}

Get Bucket Policy Status

Put Lifecycle Configuration

PUT /<bucket>/?lifecycle

Store a Lifecycle configuration for a given bucket. A lifecycle configuration is a set of rules that describes how lifecycle management for a specific object is perfomed. The following kind of rules are supported:

Note

Example with aws client:

aws s3api put-bucket-lifecycle-configuration --bucket examplebucket --lifecycle-configuration file://lifecycle.json

Payload examples

{
  "Rules": [
    {
      "ID": "Delete logs",
      "Status": "Enabled",
      "Filter": {
        "Prefix": "myapp_"
      },
      "Expiration": {
        "Days": 10
      }
    },
    {
      "Status": "Enabled",
      "Filter": {},
      "Expiration": {
        "ExpiredObjectDeleteMarker": true
      }
    },
    {
      "ID": "Delete aborted multipart",
      "Status": "Enabled",
      "Filter": {},
      "AbortIncompleteMultipartUpload": {
        "DaysAfterInitiation": 7
      }
    },
    {
      "Status": "Disabled",
      "Filter": {
        "Prefix": "logs/"
      },
      "NoncurrentVersionExpiration": {
        "NoncurrentDays": 2
      },
      "ID": "Delete old versions"
    }
  ]
}

Response

HTTP/1.1 200 OK
x-amz-id-2: aXQ+KbIrmMmoO//3bMdDTw/CnjArwje+J49Hf+j44yRb/VmbIkgIO5A+PT98Cp/6k07hf+LD2mY=
x-amz-request-id: 02D7EC4C10381EB1
Date: Wed, 14 May 2014 02:21:50 GMT
Content-Length: 0
Server: AmazonS3

Note:

Objects Expiration

Note that RSTOR Space does not currently return the object expiration date in the x-amz-expiration header. To compute the object expiration date for an object, you can proceed as follows:

GET Lifecycle Configuration

GET /<bucket>/?lifecycle

Return, if present, the current lifecycle configuration for a bucket.

Example request using the shell:

aws s3api get-bucket-lifecycle-configuration —bucket examplebucket

Using http request:

GET /examplebucket/?lifecycle HTTP/1.1
Host: s3.rstor.com
x-amz-date: Thu, 15 Nov 2012 00:17:21 GMT
Authorization: signatureValue

Note: lifecycle configuration returned may differ from the PUTed one, as it may be enriched with some more informations.

Response

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4RyTmXa3rPi4hklTXouTf0hccUjo0iCPjz6FnfIutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991C342C575321
Date: Thu, 15 Nov 2012 00:17:23 GMT
Server: AmazonS3
Content-Length: 358

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Rule>
        <ID>Archive and then delete rule</ID>
        <Filter>
           <Prefix>projectdocs/</Prefix>
        </Filter>
        <Status>Enabled</Status>
        <Expiration>
           <Days>3650</Days>
        </Expiration>
    </Rule>
</LifecycleConfiguration>

Delete Lifecycle Configuration

DELETE /<bucket>/?lifecycle

Delete, if present, a lifecycle configuration for a bucket.

Example request:

aws s3api delete-bucket-lifecycle-configuration —bucket examplebucket

Using http request:

DELETE /examplebucket/?lifecycle HTTP/1.1
Host: s3.rstor.com
Date: date
Authorization: authorization string

Response

HTTP/1.1 204 No Content
x-amz-id-2: Uuag1LuByRx9e6j5OnimrSAMPLEtRPfTaOAa==
x-amz-request-id: 656c76696e672SAMPLE5657374
Date: Wed, 14 Dec 2011 05:37:16 GMT
Connection: keep-alive

Example request

POST /bucket/path/to/object?rs-presign= HTTP/1.1
Host: [...]
Authorization: [...]
Content-Type: application/x-www-form-urlencoded
X-Amz-Content-Sha256: [...]
X-Amz-Date: [...]

ExpirationDate=2019-10-24T07%3A04%3A47.123Z

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Date: [...]
Content-Length: [...]

{
  "link": "https://s3.example.com/bucket/...",
  "accessKeyId": "RSTOR1JH..."
}

Obtain a link to the object, pre-signed with your most recently used Access Key

Parameter Description
ExpirationDate Expiration date for the pre-signed URL. Cannot be more than 30 days (720h) in the future.

Put Object Tagging

Add tagging to an object version. Overwrites tags if existing, to update tagging first get the old tagging, modify them locally and upload the new tagging.

Tagging are in the form of key-value pair: Format=Image

At most 10 tags per object version can be specified.

The length of a tag key can be up to to 128 unicode characters long. The length of a tag value can be up to to 256 unicode characters long.

Example request

PUT /bucket/objectkey?tagging&versionId=objectVersion HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

<Tagging xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><TagSet><Tag><Key>KEYTEXT</Key><Value>VALUETEXT</Value></Tag><Tag><Key>Type</Key><Value>Script</Value></Tag></TagSet></Tagging>

Example response

HTTP/1.1 200 OK
x-amz-version-id: 01DVAXPTT7XFVAMQ7P248ZNWNQ
Date: Thu, 05 Dec 2019 13:00:58 GMT
Content-Length: 0

Get Object Tagging

Return, if present, the tagging of an object.

Example request

GET /bucket/objectkey?tagging&versionId=objectVersion HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response

HTTP/1.1 200 OK
Content-Type: application/xml
Date: [...]
Content-Length: 184

<?xml version="1.0" encoding="UTF-8"?>
<Tagging xmlns=""><TagSet><Tag><Key>KEYTEXT</Key><Value>VALUETEXT</Value></Tag><Tag><Key>Type</Key><Value>Script</Value></Tag></TagSet></Tagging>

Delete Object Tagging

Delete, if present, the tagging of an object.

Example request

DELETE /bucket/objectkey?tagging&versionId=objectVersion HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]
Content-Length: 0

Example response

HTTP/1.1 204 No Content
x-amz-version-id: [...]
Date: [...]

Put Object Lock Configuration

Places an Object Lock configuration on the specified bucket. The rules specified in the Object Lock configuration will be applied by default to every new object placed in the specified bucket.

Example request

PUT /?object-lock HTTP/1.1
Host: bucketName.s3.rstor.com
<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <ObjectLockEnabled>string</ObjectLockEnabled>
   <Rule>
      <DefaultRetention>
         <Days>integer</Days>
         <Mode>string</Mode>
         <Years>integer</Years>
      </DefaultRetention>
   </Rule>
</ObjectLockConfiguration>

Example response

HTTP/1.1 200

The ObjectLockEnabled field is optional and indicates whether the bucket has an Object Lock configuration enabled (valid values: Enabled).

Get Object Lock Configuration

Retrieve the Object Lock configuration for a bucket. The rule specified in this Object Lock configuration will be applied by default to every new object placed in the specified bucket.

Example request

GET /?object-lock HTTP/1.1
Host: bucketName.s3.rstor.com

Example response

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration>
   <ObjectLockEnabled>Enabled</ObjectLockEnabled>
   <Rule>
      <DefaultRetention>
         <Days>15</Days>
      </DefaultRetention>
   </Rule>
</ObjectLockConfiguration>

Put Object LegalHold

Set a Legal-Hold lock on an existent object in a specific bucket where the S3-Locking (see CreateBucket) is enabled.

Parameter Description
VersionId specify, if present, the version of the resource where to apply the lock

The body of the request is an XML, formatted as in the example, where the field Status could assume only two values: ON, OFF

Example request

PUT /{Key+}?legal-hold&VersionId=VersionId HTTP/1.1
Host: s3.rstor.com
x-amz-date: Thu, 15 Nov 2012 00:17:21 GMT
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<LegalHold xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Status>ON</Status>
</LegalHold>

Example response

HTTP/1.1 200

Put Object Retention

Set a retention lock on an existent object in a specific bucket where the S3-Locking (see CreateBucket) is enabled.

Parameter Description
VersionId specify, if present, the version of the resource where to apply the lock

The body of the request is an XML, formatted as in the example, where the field Mode could assume only two values: GOVERNANCE, COMPLIANCE.

The RetainUntilDate field is the timestamp: should be set in the future (see RFC3339 as a format reference).

Example request

PUT /{Key+}?retention&VersionId=VersionId HTTP/1.1
Host: s3.rstor.com
x-amz-bypass-governance-retention: BypassGovernanceRetention
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<Retention xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Mode>GOVERNANCE</Mode>
   <RetainUntilDate>2020-10-02T15:00:00.05Z</RetainUntilDate>
</Retention>

Example response

HTTP/1.1 200

Get Object LegalHold

Gets an object's current Legal Hold status.

Parameter Description
versionId specify, if present, the version of the resource where to apply the lock

The body of the response is an XML, formatted as in the example, where the field Status could assume only two values: ON, OFF

Example request

GET /<object-key>?legal-hold&versionId=<version-id> HTTP/1.1

Example response

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<LegalHold>
   <Status>ON</Status>
</LegalHold>

Get Object Retention

Retrieves an object's retention settings.

Parameter Description
versionId specify, if present, the version of the resource where to apply the lock

The body of the response is an XML, formatted as in the example, where the field Mode could assume only two values: GOVERNANCE, COMPLIANCE

Example request

GET /<object-key>?legal-hold&versionId=<version-id> HTTP/1.1

Example response

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<Retention>
   <Mode>GOVERNANCE</Mode>
   <RetainUntilDate>2020-10-02T15:00:00.05Z</RetainUntilDate>
</Retention>

Put Bucket Tagging

Add tagging to a bucket. Overwrites tags if existing, to update tagging first get the old tagging, modify them locally and upload the new tagging.

Tagging are in the form of key-value pair: Format=Image

At most 10 tags per bucket can be specified. The length of a tag key can be up to to 128 unicode characters long. The length of a tag value can be up to to 256 unicode characters long.

Example request

PUT /bucket?tagging HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

<Tagging xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><TagSet><Tag><Key>KEYTEXT</Key><Value>VALUETEXT</Value></Tag><Tag><Key>Type</Key><Value>Script</Value></Tag></TagSet></Tagging>

Example response

HTTP/1.1 200 OK
Date: [...]
Content-Length: 0

Get Bucket Tagging

Return, if present, the tagging of a bucket.

Example request

GET /bucket?tagging HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response

HTTP/1.1 200 OK
Content-Type: application/xml
Date: [...]
Content-Length: 184

<?xml version="1.0" encoding="UTF-8"?>
<Tagging xmlns=""><TagSet><Tag><Key>KEYTEXT</Key><Value>VALUETEXT</Value></Tag><Tag><Key>Type</Key><Value>Script</Value></Tag></TagSet></Tagging>

Delete Bucket Tagging

Delete, if present, the tagging of a bucket.

Example request

DELETE /bucket?tagging  HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]
Content-Length: 0

Example response

HTTP/1.1 204 No Content
x-amz-version-id: [...]
Date: [...]

Put Bucket Logging

Set the logging configuration for a bucket and to specify. All logs are saved to the specified target bucket using the provided access key. To set the logging status of a bucket, you must be the bucket owner.

To delete a Bucket Logging configuration you can make a PUT passing an empty LoggingEnabledelement.

TargetBucket: is the destination bucket (where the logs will be uploaded) TargetPrefix: is the prefix of the file contains the log that will be uploaded in the TargetBucket

Then you should compose the TargetGrants. The TargetGrants must contains the Grantee element with xsi:type="AccessKey" and as a child an ID element contains the AccessKey used to perform the upload.

Example request

PUT /mybucketlog?logging HTTP/1.1
Host: 127.0.0.1:32005
Accept-Encoding: identity
User-Agent: aws-cli/1.16.287 Python/3.7.3 Linux/4.19.0-8-amd64 botocore/1.13.23
Content-MD5: NKhuLiQuQT2Icj+AzLFcTQ==
X-Amz-Date: 20200212T203404Z
X-Amz-Content-SHA256: 265e84e2b334e5566fcacffc9277caf252adc4cd4ff835bbc02df1266e116085
Content-Length: 399
<BucketLoggingStatus xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LoggingEnabled>
    <TargetBucket>targetlog</TargetBucket>
    <TargetPrefix>logs/</TargetPrefix>
    <TargetGrants>
      <Grant>
        <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AccessKey">
          <ID>AWS4XZUHH4DVBPMSZB7ODUFVVHGUXMXLY4VRJRJ4BFHJ7CGJACI4LPLA</ID>
        </Grantee>
      </Grant>
    </TargetGrants>
  </LoggingEnabled>
</BucketLoggingStatus>

Example response

HTTP/1.1 200 OK
Date: [...]
Content-Length: 0

Log format

Field Description
BucketOwner The owner id of the monitored bucket
Bucket The monitored bucket
Ts The timestamp of the action [06/Feb/2019:00:00:38 +0000]
RemoteIp The apparent IP of the requester. Intermediate proxies and firewalls might obscure the actual address of the machine making the request
Requester The AccessKey used to perform the action
RequestId The Request ID
Operation The kind of operarion (ex.: s3.PuObject, s3.GetObject)
Key The object Key (if present)
RequestUri The Request-URI part of the HTTP request message
HttpStatus The numeric HTTP status code of the response
ErrorCode The S3 Error Code, or "-" if no error occurred
BytesSent The transferred bytes
ObjectSize The size of the object transferred
TotalTime The number of milliseconds the request was in flight from the server's perspective
TurnAroundTime The number of milliseconds spent processing the request
Referer The value of the HTTP Referer header, if present
UserAgent The value of the HTTP User-Agent header
VersionId The version ID in the request (if present)
HostId Not used (is always "-")
SignatureVersion The signature version, "SigV2" or "SigV4", that was used to authenticate the request or a "-" in the other case
CipherSuite The value is SSL if the session was encrypted
Auth The type of request authentication used, "AuthHeader" for authentication headers, "QueryString" or "-" for the other cases
HostHeader Not used (is always "-")
TlsVer The TLS version used

Examples of log generated

100000000001 testlog [12/Feb/2020:20:28:02 +0100] "[::1]:34178" "AWS4XZUHH4DVBPMSZB7ODUFVVHGUXMXLY4VRJRJ4BFHJ7CGJACI4LPLA" "qfqun6v6dido" s3:PutObject "Everest" "/testlog/Everest" "200" "-" 125829120 "0" 279 274 "" "aws-sdk-go/1.28.13 (go1.13.7; linux; amd64)" 01E0XDYR0H0DA24AYE1DV1PK5S - SigV4 SSL AuthHeader - "-"
100000000001 testlog [12/Feb/2020:20:28:02 +0100] "[::1]:34178" "AWS4XZUHH4DVBPMSZB7ODUFVVHGUXMXLY4VRJRJ4BFHJ7CGJACI4LPLA" "50gzg1qj4ftt" s3:HeadObject "Everest" "/testlog/Everest" "200" "-" 125829120 125829120 1 0 "" "aws-sdk-go/1.28.13 (go1.13.7; linux; amd64)" 01E0XDYR0H0DA24AYE1DV1PK5S - SigV4 SSL AuthHeader - "-"
100000000001 testlog [12/Feb/2020:20:28:02 +0100] "[::1]:34178" "AWS4XZUHH4DVBPMSZB7ODUFVVHGUXMXLY4VRJRJ4BFHJ7CGJACI4LPLA" "eybjzx8hvf5s" s3:DeleteObject "Everest" "/testlog/Everest" "200" "-" "0" "0" 2 0 "" "aws-sdk-go/1.28.13 (go1.13.7; linux; amd64)" "-" - SigV4 SSL AuthHeader - "-"
100000000001 testlog [12/Feb/2020:20:28:02 +0100] "[::1]:34178" "AWS4XZUHH4DVBPMSZB7ODUFVVHGUXMXLY4VRJRJ4BFHJ7CGJACI4LPLA" "69srbt1hije2" s3:PutObject "foo" "/testlog/foo" "200" "-" 20 "0" 3 1 "" "aws-sdk-go/1.28.13 (go1.13.7; linux; amd64)" 01E0XDYR0TABEJXCHQ300Z8BHE - SigV4 SSL AuthHeader - "-"

Get Bucket Logging

Retrieve a bucket logging configuration.

Example request

GET /mybucketlog?logging HTTP/1.1
Host: 127.0.0.1:32005
Accept-Encoding: identity
User-Agent: aws-cli/1.16.287 Python/3.7.3 Linux/4.19.0-8-amd64 botocore/1.13.23
Content-MD5: NKhuLiQuQT2Icj+AzLFcTQ==
X-Amz-Date: 20200212T203404Z
X-Amz-Content-SHA256: 265e84e2b334e5566fcacffc9277caf252adc4cd4ff835bbc02df1266e116085
Content-Length: 0

Example response

<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus>
    <LoggingEnabled>
        <TargetBucket>targetlog</TargetBucket>
        <TargetPrefix>logs/</TargetPrefix>
        <TargetGrants>
            <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="AccessKey">
            <ID>RSTOR_KEY_123</ID>
            </Grantee>
            </Grant>
        </TargetGrants>
    </LoggingEnabled>
</BucketLoggingStatus>

RSSpeedTestDownload

Perform a download speed test. Backend sends random binary data for 10 seconds. Available only to resellers.

Example request

GET /speedtest/download HTTP/1.1
Host: [...]
Accept-Encoding: [...]
Authorization: [...]
User-Agent: [...]
X-RStor-Speedteest: 1

Example response

HTTP/1.1 200 OK
Date: [...]
Content-Type: application/octet-stream

(random binary data)

RSSpeedTestUpload

Perform an upload speed test, probably through a pre-signed link. Backend reads request body for up to 10 seconds. Available only to resellers.

Example request

PUT /speedtest/upload HTTP/1.1
Host: [...]
Accept-Encoding: [...]
Authorization: [...]
Content-Length: [...]
Content-Type: application/octet-stream
User-Agent: [...]
X-RStor-Speedteest: 1

(random binary data)

Example response

HTTP/1.1 204 No Content
Date: [...]

RSGetBucketStats

Serves per-bucket storage metrics.

Example request

GET /?rs-bucket-stats HTTP/1.1
Host: s3.example.rstorcloud.io
Authorization: [...]

Example response

{
  "abc-images": {
    "size": 6304387203,
    "objects": 74854,
    "replicationPolicy": ["DCA02", "DEN02", "SJC03"]
  },
  "abc-backups": {
    "size": 729808896,
    "objects": 229,
    "replicationPolicy": ["DCA02", "DEN02", "SJC03"]
  }
}

PutBucketCors

PUT Bucket CORS Example request #1

PUT /?cors HTTP/1.1
Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <CORSRule>
      <AllowedHeader>string</AllowedHeader>
      ...
      <AllowedMethod>string</AllowedMethod>
      ...
      <AllowedOrigin>string</AllowedOrigin>
      ...
      <ExposeHeader>string</ExposeHeader>
      ...
      <MaxAgeSeconds>integer</MaxAgeSeconds>
   </CORSRule>
   ...
</CORSConfiguration>

CORS Configuration example #1

<CORSConfiguration>
 <CORSRule>
   <AllowedOrigin>http://www.example.com</AllowedOrigin>

   <AllowedMethod>PUT</AllowedMethod>
   <AllowedMethod>POST</AllowedMethod>
   <AllowedMethod>DELETE</AllowedMethod>

   <AllowedHeader>*</AllowedHeader>
 </CORSRule>
 <CORSRule>
   <AllowedOrigin>*</AllowedOrigin>
   <AllowedMethod>GET</AllowedMethod>
 </CORSRule>
</CORSConfiguration>

Sets the cors configuration for your bucket. If the configuration exists, it replaces it.

To use this operation, you must be allowed to perform the s3:PutBucketCORS action. By default, the bucket owner has this permission and can grant it to others.

You set this configuration on a bucket so that the bucket can service cross-origin requests. For example, you might want to enable a request whose origin is http://www.example.com to access your Space bucket at my.example.bucket.com by using the browser's XMLHttpRequest capability.

To enable cross-origin resource sharing (CORS) on a bucket, you add the cors subresource to the bucket. The cors subresource is an XML document in which you configure rules that identify origins and the HTTP methods that can be executed on your bucket. The document is limited to 64 KB in size.

When RSTOR Space receives a cross-origin request (or a pre-flight OPTIONS request) against a bucket, it evaluates the cors configuration on the bucket and uses the first CORSRule rule that matches the incoming browser request to enable a cross-origin request. For a rule to match, the following conditions must be met:

In CORS Configuration example #1 the first CORSRule allows cross-origin PUT, POST, and DELETE requests whose origin is http://www.example.com origins. The rule also allows all headers in a pre-flight OPTIONS request through the Access-Control-Request-Headers header. Therefore, in response to any pre-flight OPTIONS request, RStor S3 will return any requested headers. The second rule allows cross-origin GET requests from all the origins. The '*' wildcard character refers to all origins.

CORS Configuration example #2

<CORSConfiguration>
 <CORSRule>
   <AllowedOrigin>http://www.example.com</AllowedOrigin>
   <AllowedMethod>PUT</AllowedMethod>
   <AllowedMethod>POST</AllowedMethod>
   <AllowedMethod>DELETE</AllowedMethod>
   <AllowedHeader>*</AllowedHeader>
   <MaxAgeSeconds>3000</MaxAgeSeconds>
   <ExposeHeader>x-rstor-example</ExposeHeader>
 </CORSRule>
</CORSConfiguration>

In CORS Configuration example #2, the single CORSRule includes the following additional optional parameters:

GetBucketCors

Example request

GET /?cors HTTP/1.1
Host: Bucket.s3.rstor.com

Example response

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
   <CORSRule>
      <AllowedHeader>string</AllowedHeader>
      ...
      <AllowedMethod>string</AllowedMethod>
      ...
      <AllowedOrigin>string</AllowedOrigin>
      ...
      <ExposeHeader>string</ExposeHeader>
      ...
      <MaxAgeSeconds>integer</MaxAgeSeconds>
   </CORSRule>
   ...
</CORSConfiguration>

Returns the cors configuration information set for the bucket.

To use this operation, you must have permission to perform the s3:GetBucketCORS action. By default, the bucket owner has this permission and can grant it to others.

DeleteBucketCors

Example request

DELETE /?cors HTTP/1.1
Host: Bucket.s3.rstor.com

Example response

If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

HTTP/1.1 204

Deletes the cors configuration information set for the bucket.

To use this operation, you must have permission to perform the s3:PutBucketCORS action. The bucket owner has this permission by default and can grant this permission to others.

POST s3v4 Uploads

Example form

<form action="http://s3.rstor.com/bucketname" target="s3target" enctype="multipart/form-data" method="POST">
    <!-- Key is required (key name of uploaded object) -->
    <input id="key" type="hidden" name="key" value="test_browser_myfile.txt" >
    <!-- Policy is required for authenticated requests -->
    <!-- Requests without a security policy are considered anonymous and will succeed only on a publicly writable bucket. -->
    <input id="Policy" type="hidden" name="Policy" value="[BASE64_ENCODED_SECURITY_POLICY]">
    <!-- X-Amz-Algorithm is required for authenticated requests -->
    <input id="X-Amz-Algorithm" type="hidden" name="X-Amz-Algorithm" value="AWS4-HMAC-SHA256" >
    <!-- X-Amz-Credential is required for authenticated requests -->
    <!-- <your-access-key-id>/<date>/region(unused since geographically replicated by default)/s3/aws4_request -->
    <input id="X-Amz-Credential" type="hidden" name="X-Amz-Credential"
        value="AWS4XZUHH4DVBPMSZB7ODUFVVHGUXMXLY4VRJRJ4BFHJ7CGJACI4LPLA/20200819/eu-east-1/s3/aws4_request" >
    <!-- X-Amz-Date is required for authenticated requests -->
    <!-- it is a data in ISO8601 format -->
    <input id="X-Amz-Date" type="hidden" name="X-Amz-Date" value="20200819T142942Z" >
    <!-- X-Amz-Signature is required for authenticated requests -->
    <!-- (s3v4) The HMAC-SHA256 hash of the security policy.
         This field is required if a policy document is included with the request -->
    <input id="X-Amz-Signature" type="hidden" name="X-Amz-Signature" value="[HMAC_SHA256_HASH]" >

    <!-- optional sample fields -->
    <input id="acl" type="hidden" name="acl" value="public-read" >
    <input id="success_action_redirect" type="hidden" name="success_action_redirect" value="http://somewhere.com/redir/redirect" >
    <input id="x-rstor-meta-something" type="hidden" name="x-rstor-meta-something" value="c25f87c5-2a43-4da6-901c-b3fac171e572">
    <input id="Content-Type" type="hidden" name="Content-Type" value="text/plain" >

    <!-- the file content (mandatory) -->
    <input id="file" type="file" name="file">
    <button type="submit" class="btn btn-default">Upload</button>
</form>

The POST operation adds an object to a specified bucket using HTML forms. POST is an alternate form of PUT that enables browser-based uploads as a way of putting objects in buckets. Parameters that are passed to PUT via HTTP Headers are instead passed as form fields to POST in the multipart/form-data encoded message body. You must have WRITE access on a bucket to add an object to it. RSTOR Space never stores partial objects: if you receive a successful response, you can be confident the entire object was stored.

RSTOR Space is a distributed system. If RSTOR Space receives multiple write requests for the same object simultaneously, all but the last object written is overwritten.

To ensure that data is not corrupted traversing the network, use the Content-MD5 form field. When you use this form field, RSTOR Space checks the object against the provided MD5 value. If they do not match, RSTOR Space returns an error. Additionally, you can calculate the MD5 value while posting an object to RSTOR Space and compare the returned ETag to the calculated MD5 value. The ETag only reflects changes to the contents of an object, not its metadata.

Policy

Example policy

{ "expiration": "2007-12-01T12:00:00.000Z",
  "conditions": [
    {"acl": "public-read" },
    {"bucket": "mybucket" },
    ["starts-with", "$key", "user/paul/"],
  ]
}

The policy required for making authenticated requests using HTTP POST is a UTF-8 and base64-encoded document written in JavaScript Object Notation (JSON) that specifies conditions that the request must meet. Depending on how you design your policy document, you can control the access granularity per-upload, per-user, for all uploads, or according to other designs that meet your needs.

The POST policy always contains the expiration and conditions elements. The example policy uses two condition matching types (exact matching and starts-with matching). The following sections describe these elements.

The expiration element specifies the expiration date and time of the POST policy in ISO8601 GMT date format. For example, 2013-08-01T12:00:00.000Z specifies that the POST policy is not valid after midnight GMT on August 1, 2013.

Example request

POST / HTTP/1.1
Host: destinationBucket.s3.rstor.com
User-Agent: browser_dataAmazon
Accept: file_types
Accept-Language: Regions
Accept-Encoding: encoding
Accept-Charset: character_set
Keep-Alive: 300
Connection: keep-alive
Content-Type: multipart/form-data; boundary=9431149156168
Content-Length: length

--9431149156168
Content-Disposition: form-data; name="key"

acl
--9431149156168
Content-Disposition: form-data; name="tagging"

<Tagging><TagSet><Tag><Key>Tag Name</Key><Value>Tag Value</Value></Tag></TagSet></Tagging>
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"

success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Type"

content_type
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-uuid"

uuid
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-tag"

metadata
--9431149156168
Content-Disposition: form-data; name="RStorAccessKeyId"

access-key-id
--9431149156168
Content-Disposition: form-data; name="Policy"

encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"

signature=
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg

file_content
--9431149156168
Content-Disposition: form-data; name="submit"

Upload to RSTOR Space
--9431149156168--

Condition matching

Following is a table that describes condition matching types that you can use to specify POST policy conditions (described in the next section). Although you must specify one condition for each form field that you specify in the form, you can create more complex matching criteria by specifying multiple conditions for a form field.

Condition Match Type Description
Exact Matches The form field value must match the value specified. This example indicates that the ACL must be set to public-read:
{"acl": "public-read" }
This example is an alternate way to indicate that the ACL must be set to public-read:
[ "eq", "$acl", "public-read" ]
Starts With The value must start with the specified value. This example indicates that the object key must start with user/user1:
["starts-with", "$key", "user/user1/"]
Matching Content-Types in a Comma-Separated List Content-Types values for a starts-with condition that include commas are interpreted as lists. Each value in the list must meet the condition for the whole condition to pass. For example, given the following condition:
["starts-with", "$Content-Type", "image/"]
The following value would pass the condition:
"image/jpg,image/png,image/gif"
The following value would not pass the condition:
["image/jpg,text/plain"]
Note: data elements other than Content-Type are treated as strings, regardless of the presence of commas.
Matching Any Content To configure the POST policy to allow any content within a form field, use starts-with with an empty value (""). This example allows any value for success_action_redirect:
["starts-with", "$success_action_redirect", ""]
Specifying Ranges For form fields that accept a range, separate the upper and lower limit with a comma. This example allows a file size from 1 to 10 MiB:
["content-length-range", 1048576, 10485760]

Conditions

The conditions in a POST policy is an array of objects, each of which is used to validate the request. You can use these conditions to restrict what is allowed in the request. For example, the provided example policy conditions require the following:

Each form field that you specify in a form (except x-amz-signature, file, policy, and field names that have an x-ignore- prefix) must appear in the list of conditions.

Policy document conditions are described in the following table.

Element Name Description
acl Specifies the ACL value that must be used in the form submission.
This condition supports exact matching and starts-with condition match type discussed in the preceding section.
bucket Specifies the acceptable bucket name.
This condition supports exact matching condition match type.
content-length-range The minimum and maximum allowable size for the uploaded content.
This condition supports content-length-range condition match type.
Cache-Control
Content-Type
Content-Disposition
Content-Encoding
Expires		 REST-specific headers. For more information, see POST Object.
This condition supports exact matching and starts-with condition match type.
key The acceptable key name or a prefix of the uploaded object.
This condition supports exact matching and starts-with condition match type.
success_action_redirect
redirect		 The URL to which the client is redirected upon successful upload.
This condition supports exact matching and starts-with condition match type.
success_action_status The status code returned to the client upon successful upload if success_action_redirect is not specified.
This condition supports exact matching.
x-amz-algorithm The signing algorithm that must be used during signature calculation. For AWS Signature Version 4, the value is AWS4-HMAC-SHA256.
This condition supports exact matching.
x-amz-credential The credentials that you used to calculate the signature. It provides access key ID and scope information identifying region and service for which the signature is valid. This should be the same scope you used in calculating the signing key for signature calculation.
It is a string of the following form:

<your-access-key-id>/<date>/<optional-rstor-region>/s3/aws4_request

For example:

RSTORACCESSKEY92724/20130728/us-east-1/s3/aws4_request

For RSTOR Space, the service string is always s3. Regions are specified for compatibility reasons, although multi-geographical distribution is automatically enforced. This is required if a POST policy document is included with the request.
This condition supports exact matching.
x-amz-date The date value specified in the ISO8601 formatted string. For example, 20130728T000000Z. The date must be same that you used in creating the signing key for signature calculation.
This is required if a POST policy document is included with the request.
This condition supports exact matching.
x-rstor-meta-* User-specified metadata.
This condition supports exact matching and starts-with condition match type.
x-rstor-* Any other documented RStor-specific meta
This condition supports exact matching.

Character Escaping

Characters that must be escaped within a POST policy document are described in the following table.

Escape Sequence Description
\ Backslash
\$ Dollar symbol
\b Backspace
\f Form feed
\n New line
\r Carriage return
\t Horizontal tab
\v Vertical tab
\uxxxx All Unicode characters

Transporter

The Transporter endpoint copies buckets between S3, Azure and GCP storages. This API is exposed to our users and will be accessible from the GUI. Requests to this endpoint must be signed with AWS Signature V4 or V2, specifying "transporter" as service.

Supported cloud storages

Cloud endpoint parameters

The following parameters describes a cloud storage endpoint:

Parameter Name Meaning Example Values Required For
type Type of cloud storage (protocol/provider) s3v2, s3v4, azure, gcp, rstor, aws any endpoint
[DESTINATION ONLY] subtype storage class type aws-s3-standard, aws-s3-reduced-redundancy, aws-s3-standard-infrequent-access, aws-s3-one-zone-infrequent-access, aws-s3-intelligent-tiering, aws-s3-glacier, aws-s3-glacier-deep-archive, gcp-s3-standard, gcp-s3-nearline, gcp-s3-coldline, azure-s3-hot, azure-s3-cool, azure-s3-archive optional for any destination endpoint
accessKey endpoint access key ACCESS_KEY any endpoint
secretKey endpoint private key PRIVATE_KEY any endpoint
bucket bucket name bucket_name any endpoint
endpoint endpoint url https://s3.eu-central-1.amazonaws.com any endpoint
region region eu-central-1 s3v4, aws, rstor and GCP endpoints

The subtype parameter is only used for destination (source reading from non-default storage is unsupported at this time) migration configurations and is optional. When empty or not specified the default writing storage class for the specified CSP type will be automatically used. Additional cold storage options are not supported at this time (e.g. vault lock).

Other migration options

The following parameters are additional options for the migration:

Parameter Name Meaning Example Values Required For
deleteAfterUpload we will deleted each object after a successful copy false, true none

Cloud storage endpoint examples

RStor (rstor)

{
  "type":"rstor",
  "accessKey":"S3 Access Key",
  "secretKey":"S3 Secret Key",
  "bucket":"S3 Bucket Name",
  "endpoint":"https://s3.region.endpoint.com",
  "region":"region"
}

AWS S3 (aws)

{
  "type":"aws",
  "accessKey":"S3 Access Key",
  "secretKey":"S3 Secret Key",
  "bucket":"S3 Bucket Name",
  "endpoint":"https://s3.region.endpoint.com",
  "region":"region"
}

Azure (azure)

{
  "type":"azure",
  "accessKey":"Account name",
  "secretKey":"Account key",
  "bucket":"Container name",
  "endpoint":"https://account_name.blob.core.windows.net",
}

Google Cloud Storage (gcp)

To obtain Google Access Key and Google Secret Key follow the docs here

{
  "type":"gcp",
  "accessKey":"Google Access Key",
  "secretKey":"Google Secret Key",
  "bucket":"Bucket name",
  "endpoint":"https://storage.googleapis.com",
  "region":"Region"
}

Google Cloud Storage with Service Account Key (gcp-native)

Google cloud storage endpoint employing the native key bound to a service account instead of the access/secret key pair.

{
  "type":"gcp-native",
  "bucket":"Bucket name",
  "endpoint":"https://storage.googleapis.com/storage/v1/",
  "region":"Region",
  "gcsConfig": <KEY_FILE_PAYLOAD>
}

<KEY_FILE_PAYLOAD> corresponds to the content of the file generated by google cloud platform while creating a key for a service account, which contains all the information about the created key. Refer to the docs to learn how to obtain such key file.

S3 signature v4 (s3v4)

S3 signature v4 (s3v4)

{
  "type":"s3v4",
  "accessKey":"S3 Access Key",
  "secretKey":"S3 Secret Key",
  "bucket":"S3 Bucket Name",
  "endpoint":"https://s3.region.endpoint.com",
  "region":"region"
}

S3 signature v2 (s3v2) [deprecated]

{
  "type":"s3v2",
  "accessKey":"S3 Access Key",
  "secretKey":"S3 Secret Key",
  "bucket":"S3 Bucket Name",
  "endpoint":"https://s3.endpoint.com",
}

Post Migration

Create a new data migration between two cloud endpoints. The source and the destination of the migration are specified as json documents.

Query parameters:

Body:

The JSON request body consists in the following sections:

Storage parameters:

Field Desc Notes
type The type of the source {gcp,aws,s3v4} required
accessKey The access key required
secretKey The relative secret key required
bucket The name of the bucket (source and dest can have different name) required
prefix If specified only object with this prefix will be moved optional, valid only for the source
endpoint s3 endpoint required
forceSSES3 If specified forces SSES3 encryption when writing objects optional, valid only for destination

Scheduling parameter It's possible to create a recurring migration specifyng a crontab section with two fields:

...
"crontab": {
    "spec": "* * * * *",
    "maxRuns": 100
 }
Field Desc Notes
spec The cron specification (see https://en.wikipedia.org/wiki/Cron) required
maxRuns If specified and greather than zero set maimum number of runs for that migration optional

spec examples:

Value Desc
@hourly Run every hour
@daily Run once per day hour (at midnight)
@weekly Run once a week at midnight on Sunday morning (0 0 * * 0 )
* * * * * Run every minutes
0,15,30,45 * * * * Run every 15 minutes
0 0 1 * * Run at the 1st of every months
45 23 * * 6 Run at 23:45 (11:45 PM) every Saturday

Notes: we don't support range

Examples

Example request

POST /migrations HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

{
    "source": {
        "type": "s3v4",
        "accessKey": "ACCESS_KEY",
        "secretKey": "PRIVATE_KEY",
        "bucket": "bucket_name",
        "prefix": "prefix_path",
        "endpoint": "https://s3.rstorcloud.io"
    },
    "destination": {
        "type": "s3v4",
        "accessKey": "ACCESS_KEY",
        "secretKey": "PRIVATE_KEY",
        "bucket": "other_bucket_name",
        "endpoint": "https://s3.rstorcloud.io",
        "forceSSES3": true
    }
}

Example response

HTTP/1.1 201 OK
Content-Length: X

{
    "root": "example",
    "username": "username",
    "id": "migration_id",
}

Get Migrations

List all the migrations submitted by your user. For security reasons, credentials are not shown.

Example request

GET /migrations HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response

HTTP/1.1 200 OK
Date: [...]
Content-Length: X

[
  {
    "root": "example",
    "username": "testuser@example.com",
    "id": "migration_id",
    "source": {
        "type": "s3v4",
        "bucket": "bucket_name",
        "endpoint": "https://s3.rstorcloud.io"
    },
    "destination": {
        "type": "s3v4",
        "bucket": "other_bucket_name",
        "endpoint": "https://s3.rstorcloud.io"
    }
  }
]

Test storage configuration

Verify a storage configuration. Storage configuration and operations to be checked must be sent as a JSON document.

Example request

POST /test-storage HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

{
  "config": {
    "type": "s3v4",
    "accessKey": "ACCESS_KEY",
    "secretKey": "PRIVATE_KEY",
    "bucket": "bucket_name",
    "endpoint": "https://s3.rstorcloud.io"
   },
   "read": true,
   "write": true,
   "delete": false
}

Example response

HTTP/1.1 200 OK
Date: [...]

Example negative response

HTTP/1.1 400 Bad request
Date: [...]
Content-Length: X

{
    "error": "invalid configuration for the storage",
    "details":"NoSuchBucket, details: NoSuchBucket: The specified bucket does not exist"
}

Get Migration State

Check the migration state. If no worker started the migration the API will answer with a 404.

Example request

GET /state/migration_id HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response

HTTP/1.1 200 OK
Date: [...]
Content-Length: X

{
    "root": "example",
    "id": "migration_id",
    "listingCompleted": true,
    "lastKey": "",
    "startTime": "2020-03-26T13:26:44.546Z",
    "lastUpdate": "2020-03-26T13:26:45.404Z",
    "filesFound": 10,
    "filesCompleted": 10,
    "filesFailed": 0,
    "bytesTransmitted": 36546,
    "errors": ["error during ...","error accessing ..."]
    "state": 2,
    "stateDescription": "Completed"
}

The state field can have one of the following values:

Value State
0 Started
1 Running
2 Completed
3 Terminated
4 Waiting
5 Paused
6 Failed
7 Completed with errors
8 Source list completed
9 Queued
10 Verified

Verified in this context means that the pre-flight checks for reading/writing permissions on the source/target storages have been successfully completed.

The stateDescription field contains a human readable description in PascalCase of the above.

Abort migration

Aborts the given migration.

Example request

POST /abort/id HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response

HTTP/1.1 200 OK
Date: [...]

Retry migration

Retries the given migration. Responds with 404 if migration does not exist. Responds with 400 if migration is not finished.

Example request

POST /retry/id HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response

HTTP/1.1 204 OK
Date: [...]

Pause migration

Pause the given migration. To resume a migration set "paused" to false

Example request

POST /pause/id HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]
{"paused":true}

Example response

HTTP/1.1 200 OK
Date: [...]

Sync Migration (incremental sync)

Create a new incremental sync migration between two cloud endpoints. There is always a source endpoint A and a destination endpoint B: any file added to the source endpoint A will be mirrored to B. Files added to B will not be added to A (unless there is a second incremental sync launched with source B and destination A). The synchronization will be incremental i.e. only files present in A and missing in B will be transferred (no unnecessary transfers will take place for the others). The source and the destination of the migration are specified as json documents. It's also possible to specify an original migration passing the migrationd-id as unique parameter without a body.

Query parameters:

Storage parameters:

Field Desc Notes
type The type of the source {gcp,aws,s3v4} required
accessKey The access key required
secretKey The relative secret key required
bucket The name of the bucket (source and dest can have different name) required
prefix If specified only object with this prefix will be moved optional, valid only for the source
endpoint s3 endpoint required

Examples

Example request

POST /sync HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

{
    "source": {
        "type": "s3v4",
        "accessKey": "ACCESS_KEY",
        "secretKey": "PRIVATE_KEY",
        "bucket": "bucket_name",
        "prefix": "prefix_path",
        "endpoint": "https://s3.rstorcloud.io"
    },
    "destination": {
        "type": "s3v4",
        "accessKey": "ACCESS_KEY",
        "secretKey": "PRIVATE_KEY",
        "bucket": "other_bucket_name",
        "endpoint": "https://s3.rstorcloud.io"
    }
}

Example response

HTTP/1.1 201 OK
Content-Length: X
Content-Type: 'application/json; charset=utf-8'

{
    "root": "example",
    "id": "migration_id",
}

Example request using an id

POST /sync/926dd67a-5475-43b3-9f7e-c6f2d5177bf7 HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response

HTTP/1.1 201 OK
Content-Length: X
Content-Type: 'application/json; charset=utf-8'

{
    "root": "example",
    "id": "migration_id",
}

List Buckets

List available buckets for an s3 endpoint.

Example request

POST /list-buckets HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

{
  "type": "s3v4",
  "accessKey": "RSTOR15Q...",
  "secretKey": "Am3YB4V...",
  "region": "us-east-1",
  "endpoint": "example.com"
}

Example response

HTTP/1.1 200 OK
Date: [...]
Content-Length: X

[
 {"name":"bucket_1_name"},
 {"name":"bucket_2_name"}
]

Bandwidth limiting

Get or set the bandwidth limit for a migration, so that it doesn't consume the whole bandwidth available.

Get bandwidth limit

A value of bytesPerSecond equal to zero stands for no limit currently set for this migration.

Example request

GET /bandwidth/migration_id HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response

HTTP/1.1 200 OK
Date: [...]
Content-Length: X

{
    "migrationID": "4d38d4a2-a464-4c8d-93c9-7f921bade7d9",
    "bytesPerSecond": 5000000
}

Set bandwidth limit

This call allows the caller to set a (possibly different) bandwidth limit to several migrations at once. Allowed bytesPerSecond values are 0 (stands for no limit) or >= 1000.

Example request

POST /bandwidth HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

[
    {
        "migrationID": "7684fbee-f67a-4c45-b39f-0993da74c1ce",
        "bytesPerSecond": 5000000
    }
]

Example response

HTTP/1.1 200 OK
Date: [...]

Recurring Migration

A recurring migration is a migration with a scheduling configuration associated. We are supporting the cron syntax specification (see https://en.wikipedia.org/wiki/Cron for more details).

Set (create or update) a scheduling configuration

API: /recurring/migration/:migration-id Content-Type: JSON Method: POST

Field Desc Notes
spec The cron spec (ex.: "@hourly", "0,30 * * * *") required
maxRuns The maximum number of runs (0 means unlimited) required
runs The current number of runs (if 0 reset the counter) optional
enabled If true enable scheduling config, otherwise disable it optional (default True)

Example request (set a weekly scheduling for a migration)

POST /recurring/migration/7684fbee-f67a-4c45-b39f-0993da74c1ce HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

  {
    "spec": "@weekly",
    "maxRuns": 0 // unlimited run
  }

Example response

HTTP/1.1 200 OK
Date: [...]

Delete a scheduling configuration

Remove a scheduling configuration for a specified migration.

API: /recurring/migration/:migration-id Content-Type: JSON Method: DELETE

Example request (set a weekly scheduling for a migration)

DELETE /recurring/migration/7684fbee-f67a-4c45-b39f-0993da74c1ce HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response

HTTP/1.1 200 OK
Date: [...]

List Migration Plans

Example request

GET /plans HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response (success)

HTTP/1.1 200 OK
Date: [...]

[
  {
    "id": "86524853-7b4d-4e0a-bf3f-b5e99de46402",
    "root": "example",
    "config": {
      "source": {
        "type": "rstor",
        "bucket": "test-s",
        "endpoint": "https://s3.rstorcloud.io",
        "region": "us-east-1"
      },
      "destination": {
        "type": "rstor",
        "bucket": "test-d",
        "endpoint": "https://s3.rstorcloud.io",
        "region": "us-east-1"
      },
      "sync": true,
      "syncMode": "simple",
      "skipVerify": false
    },
    "status": "queued",
    "createdAt": "2021-06-07T09:55:08.509865Z",
    "associatedMigrationsIDs": []
  },
  {
    "id": "7d61d212-5280-405f-afe1-603c262b938d",
    "root": "example",
    "config": {
      "source": {
        "type": "rstor",
        "bucket": "test-s",
        "endpoint": "https://s3.rstorcloud.io",
        "region": "us-east-1"
      },
      "destination": {
        "type": "rstor",
        "bucket": "test-d",
        "endpoint": "https://s3.rstorcloud.io",
        "region": "us-east-1"
      },
      "sync": true,
      "syncMode": "simple",
      "skipVerify": false
    },
    "status": "queued",
    "createdAt": "2021-06-07T09:55:09.894507Z",
    "endedAt": "2021-06-07T10:30:11.543512Z",
    "associatedMigrationsIDs": [
      {
        "root": "example",
        "id": "4d34b4d5-b17e-4497-885e-0d3e6efcc05a"
      }
    ]
  },
  {
    "id": "c3a01735-dc2e-49e1-b0c0-941094404c67",
    "root": "example",
    "config": {
      "source": {
        "type": "rstor",
        "bucket": "test-s",
        "endpoint": "https://s3.rstorcloud.io",
        "region": "us-east-1"
      },
      "destination": {
        "type": "rstor",
        "bucket": "test-d",
        "endpoint": "https://s3.rstorcloud.io",
        "region": "us-east-1"
      },
      "sync": true,
      "syncMode": "by-time",
      "skipVerify": false
    },
    "status": "queued",
    "createdAt": "2021-06-07T09:55:10.726305Z",
    "endedAt": "2021-06-07T10:30:11.543512Z",
    "associatedMigrationsIDs": []
  }
]

GET /plans

List migrations plans and associated migrations.

Response

HTTP status codes:

Body: a JSON document listing all the plans. Migration plans returned here don’t contain statistics and errors. Associated migrations are reported as ID-root pairs in an array.

Get Migration Plan

Example request

GET /plans/7d61d212-5280-405f-afe1-603c262b938d HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response (success)

HTTP/1.1 200 OK
Date: [...]

{
  "id": "7d61d212-5280-405f-afe1-603c262b938d",
  "root": "example",
  "config": {
    "source": {
      "type": "rstor",
      "bucket": "test-s",
      "endpoint": "https://s3.rstorcloud.io",
      "region": "us-east-1"
    },
    "destination": {
      "type": "rstor",
      "bucket": "test-d",
      "endpoint": "https://s3.rstorcloud.io",
      "region": "us-east-1"
    },
    "sync": true,
    "syncMode": "simple",
    "skipVerify": false
  },
  "status": "queued",
  "errors": [],
  "associatedMigrationsIDs": [
    {
      "root": "example",
      "id": "4d34b4d5-b17e-4497-885e-0d3e6efcc05a"
    }
  ],
  "createdAt": "2021-06-07T09:55:09.894507Z",
  "endedAt": null,
  "totObjects": 0,
  "totSize": 0,
  "distribution": [
    {
      "label": "< 10B",
      "max": 10,
      "min": 0,
      "value": 0
    },
    {
      "label": "10B - 100B",
      "max": 100,
      "min": 11,
      "value": 0
    },
    {
      "label": "100B - 1KB",
      "max": 1000,
      "min": 101,
      "value": 0
    },
    {
      "label": "1KB - 5KB",
      "max": 5000,
      "min": 1001,
      "value": 0
    },
    {
      "label": "5KB - 10KB",
      "max": 10000,
      "min": 5001,
      "value": 0
    },
    {
      "label": "10KB - 100KB",
      "max": 100000,
      "min": 10001,
      "value": 0
    },
    {
      "label": "100KB - 1MB",
      "max": 1000000,
      "min": 100001,
      "value": 0
    },
    {
      "label": "1MB - 10MB",
      "max": 10000000,
      "min": 1000001,
      "value": 0
    },
    {
      "label": "10MB - 100MB",
      "max": 100000000,
      "min": 10000001,
      "value": 0
    },
    {
      "label": "100MB - 1GB",
      "max": 1000000000,
      "min": 100000001,
      "value": 0
    },
    {
      "label": "1GB - 10GB",
      "max": 10000000000,
      "min": 1000000001,
      "value": 0
    },
    {
      "label": "> 10GB",
      "max": 100000000000,
      "min": 10000000001,
      "value": 0
    }
  ]
}

GET /plans/:plan:id

Retrieve info about a specific migration plan indicated by the :plan-id URL parameter. This endpoint returns more information than the listing one, including the distribution of the objects, the total number of objects and the total size of the objects.

URL parameters

Field Desc Notes
plan-id The id of the migration plan to be returned required

Response

HTTP status codes:

Body: a JSON document containing information about the specified migration plan. The response includes statistics, errors, the status of the plan and associated migrations IDs.

Post Migration Plan

Example request

POST /plans HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

{
  "source": {
    "type": "rstor",
    "accessKey": "<access-key>",
    "secretKey": "<secret-key>",
    "bucket": "source-bucket",
    "region": "us-east-1",
    "prefix": "",
    "endpoint": "https://s3.rstor.pre-rstor.com"
  },
  "destination": {
    "type": "rstor",
    "accessKey": "<access-key>",
    "secretKey": "<secret-key>",
    "bucket": "dest-bucket",
    "endpoint": "https://s3.rstor.pre-rstor.com",
    "prefix": "",
    "region": "us-east-1"
  },
  "skipVerify": false,
  "syncMode": "simple",
  "sync": false
}

Example response (success)

HTTP/1.1 200 OK
Date: [...]

{
  "planID": "7d61d212-5280-405f-afe1-603c262b938d"
}

Example response (invalid conf)

HTTP/1.1 400 Bad Request
Date: [...]

{
  "details": "source errors: <conf-errors>"
}

POST /plans

Create a new migration plan. The plan will be 'stand-alone' and not associated with any existing migration. Configuration parameters must be provided in the JSON-formatted HTTP request body. Note that the parameters resemble the post migration API ones.

Please note that the migration plan feature supports the same 'running modes' of a normal incremental sync, if the plan is set to be a sync. The sync mode defaults to simple if not provided. Valid values are simple or by-time.

JSON-body parameters

Field Desc Notes
source Source storage parameters (more details below) required
destination Destination storage parameters (more details below) required
sync Controls the 'mode' of the plan (regular or sync) bool, defaults to false
syncMode Controls the mode of a plan if it is a sync (possible values are simple or by-time) string, defaults to simple if not provided and sync is true
skipVerify Controls if preliminary checks should be skipped when starting the plan bool, defaults to false

Storage parameters

Field Desc Notes
type The type of the source {gcp,aws,s3v4} required
accessKey The access key required
secretKey The secret key required
bucket The name of the bucket required
endpoint The s3 endpoint required

Response

HTTP status codes:

Body: a JSON document with the ID of the newly created migration plan.

Post Migration Plan From Migration

Example request

POST /plans/4d34b4d5-b17e-4497-885e-0d3e6efcc05a HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response (success)

HTTP/1.1 200 OK
Date: [...]

{
  "planID": "7d61d212-5280-405f-afe1-603c262b938d"
}

Example response (migration not found)

HTTP/1.1 404 Not Found
Date: [...]

{
  "error": "not found"
}

POST /plans/:migration-id

Create a new migration plan using (copying) necessary configurations from an existing migration. The :migration-id parameter in the URL indicates which migration should be used. The plan will be associated with the migration. No configuration parameters must be provided in the request body since everything will be taken from the existing migration.

Please note that sync migrations will originate sync plans and regular migrations will originate regular plans. The sync mode is inherited from the original migration (if it is relevant).

URL parameters

Field Desc Notes
migration-id The id of the migration to be used to generate the plan required

Response

HTTP status codes:

Body: a JSON document with the ID of the newly created migration plan.

Delete Migration Plan

Example request

DELETE /plans/7d61d212-5280-405f-afe1-603c262b938d HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response (success)

HTTP/1.1 200 OK
Date: [...]

Example response (plan ended)

HTTP/1.1 409 Conflict
Date: [...]

{
  "details": "migration plan already ended, current status: ended"
}

DELETE /plans/:plan-id

Abort a migration plan. The plan must be not ended, that is, it must be in one of the following states:

URL parameters

Field Desc Notes
plan-id The id of the migration plan to be aborted required

Response

HTTP status codes:

Body: empty in case of success.

Post Migration From Plan

Example request

POST /migration-from-plan/7d61d212-5280-405f-afe1-603c262b938d HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

{
  "crontab": {
    "spec": "* * * * *",
    "maxRuns": 100
  },
  "enableStatistics": true,
  "notifications": [
    {
      "event": "reports ready",
      "carrier": "email",
      "destination": [
        "example@gmail.com"
      ]
    }
  ]
}

Example response (success)

HTTP/1.1 200 OK
Date: [...]

{
  "id": "4d34b4d5-b17e-4497-885e-0d3e6efcc05a",
  "root": "example"
}

POST /migration-from-plan/:plan-id

Create a new migration from an existing plan. The plan used to start a migration must be a regular plan, not an incremental sync. The parameters to be used for the new migration could be provided in the JSON-formatted body, as with the Post Migration API. Note however that the fields source, destination and no-verify are overridden with the values taken from the specified migration plan. Other fields could still be provided in the body or in the URL query string (e.g. notifications, crontab conf, bandwidth). For more info about these parameters look at the Post Migration API.

JSON-body parameters

Field Desc Notes
crontab Look at the Post Migration API
enableStatistics Look at the Post Migration API bool, defaults to false
notification Look at the Post Migration API array of objects, defaults to false

Query parameters

Field Desc Notes
bandwidth-limit Look at the Post Migration API

URL parameters

Field Desc Notes
plan-id The id of the migration plan to be used to generate the migration required

Response

HTTP status codes:

Body: a JSON document containing root and ID of the generated migration.

Sync Migration From Plan

Example request

POST /sync-from-plan/7d61d212-5280-405f-afe1-603c262b938d HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

{
  "crontab": {
    "spec": "* * * * *",
    "maxRuns": 100
  },
  "enableStatistics": true,
  "notifications": [
    {
      "event": "reports ready",
      "carrier": "email",
      "destination": [
        "example@gmail.com"
      ]
    }
  ]
}

Example response (success)

HTTP/1.1 200 OK
Date: [...]

{
  "id": "4d34b4d5-b17e-4497-885e-0d3e6efcc05a",
  "root": "example"
}

POST /sync-from-plan/:plan-id

Create a new incremental sync from an existing plan. The plan used to start a migration must be a sync plan, not an regular one. The parameters to be used for the new migration could be provided in the JSON-formatted body, as with the Post Migration API.Note however that the fields source, destination and no-verify are overridden with the values taken from the specified migration plan. Other fields could still be provided in the body or in the URL query string (e.g. notifications, crontab conf, bandwidth). For more info about these parameters look at the Sync Migration API.

JSON-body parameters

Field Desc Notes
crontab Look at the Sync Migration API
enableStatistics Look at the Sync Migration API bool, defaults to false
notification Look at the Sync Migration API array of objects, defaults to false

Query parameters

Field Desc Notes
bandwidth-limit Look at the Sync Migration API
sync-mode Overrides the sync-mode of the plan (if present)

URL parameters

Field Desc Notes
plan-id The id of the migration plan to be used to generate the sync required

Response

HTTP status codes:

Body: a JSON document containing root and ID of the generated sync migration.

Migration Reports

During migrations, reports are collected by the workers and sent to the transporter server.

The following information about each object transfer is recorded: For successful transfers: source bucket, destination bucket, object key, start time (UTC timezone), connection duration (seconds), copy duration (seconds), finish time (UTC timezone), copied bytes, eTag at source, eTag at destination, copied tags (boolean), copied system metadata (boolean), copied user metadata (boolean), SSE enabled (boolean).

For failed transfers, along with the above fields, 4 more error fields are present: source reading error, destination writing error, rstor writing error, source delete error.

Retrieve error reports for an existing migration (running or ended)

API: /reports/errors/:migration-id

Method: GET

Basic filtering and pagination could be controlled via some query string parameters.

Field Desc Notes
maxEntries Max number of error reports that the API can return optional (default=300, cap=1000)
start Return reports starting from the start-th report optional (default=0, from the start)
key Return reports related to this object key optional (missing=don't filter for key)

Example request

GET /reports/errors/7684fbee-f67a-4c45-b39f-0993da74c1ce HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response

HTTP/1.1 200 OK
Date: [...]
Content-Length: X
Content-Encoding: application/json

{
   "reports": [ 
     {
        "sourceBucket": "test-s",
        "destinationBucket": "test-d",
        "objectKey": "apierror/server_error.go",
        "startTime": "2021-04-19T12:55:53Z",
        "connectionDuration": 0,
        "copyDuration": 0,
        "finishTime": "2021-04-19T12:55:53Z",
        "bytesCopied": 0,
        "sourceETag": "",
        "destinationETag": "",
        "tagsCopied": false,
        "systemMetadataCopied": false,
        "userMetadataCopied": false,
        "sseEnabled": false,
        "sourceReadingErr": "nosuchkey: the specified key does not exist status code: 404, request id: , host id: ",
        "destinationWritingErr": "",
        "rstorWritingErr": "",
        "sourceDeleteErr": ""
     },
     {
        "sourceBucket": "test-s",
        "destinationBucket": "test-d",
        "objectKey": "auth/rampAuthenticator.go",
        "startTime": "2021-04-19T12:55:53Z",
        "connectionDuration": 0,
        "copyDuration": 0,
        "finishTime": "2021-04-19T12:55:53Z",
        "bytesCopied": 0,
        "sourceETag": "",
        "destinationETag": "",
        "tagsCopied": false,
        "systemMetadataCopied": false,
        "userMetadataCopied": false,
        "sseEnabled": false,
        "sourceReadingErr": "nosuchkey: the specified key does not exist status code: 404, request id: , host id: ",
        "destinationWritingErr": "",
        "rstorWritingErr": "",
        "sourceDeleteErr": ""
     }
   ],
   "filter": {
        "migrationID: "",
        "key": ""
   },
   "pagination": {
        "start": 0,
        "maxEntries": 300,
        "end": true
   }
}

Ask for migrations reports preparation (ended)

API: /reports/prepare/:migration-id Method: POST

Reports must be prepared upon a user request. When the task is completed, the user (and other users present in the notification section of the post migration request, for cloud-to-cloud migrations) will be notified via email. The email will contain a link (with a token) to download the reports.

When reports preparation ends, further reports preparation could be asked. Reports are prepared as a compressed tar archive. Each file in the archive contains the reports in CSV format with an initial explanatory header. Also report preparation failure will be notified via email.

Example request

POST /reports/prepare/7684fbee-f67a-4c45-b39f-0993da74c1ce HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response

HTTP/1.1 200 OK
Date: [...]

Example response #2 (reports already under preparation)

HTTP/1.1 409 Conflict
Date: [...]

Get reports preparation status

API: /reports/prepare/:migration-id Method: GET

Clients could verify if reports for a specific migration are under preparation. Reports are not considered under preparation if they were never asked, or the last preparation has ended.

Example request

GET /reports/prepare/7684fbee-f67a-4c45-b39f-0993da74c1ce HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]

Example response (no reports preparation)

HTTP/1.1 200 OK
Date: [...]
Content-Length: X
Content-Encoding: application/json

{
    "isPreparing": false
}

Example response #2 (reports under preparation)

HTTP/1.1 200 OK
Date: [...]
Content-Length: X
Content-Encoding: application/json

{
    "isPreparing": true
}

Download reports of a migration (after report preparation)

API: /reports/download/:migration-id?token=:token Method: GET

After preparation, reports could be downloaded. The user has received an email with a link to this endpoint, and a download-token is embedded in the link. If the request to this endpoint includes the correct, the downloading of the compressed tar archive starts.

Note: this API is public and does not need to be signed like others APIs.

Example request

GET /reports/download/7684fbee-f67a-4c45-b39f-0993da74c1ce?token=<some_token> HTTP/1.1
Host: [...]

Example response

HTTP/1.1 200 OK
Content-Encoding: application/tar+gzip
Date: [...]

# body containing the compressed tar archive data

Example response #2 (token expired or wrong)

HTTP/1.1 404 Not Found
Date: [...]

Migration Stats

This module introduces three new APIs to enable statistics for our migrations. In order to enable statics for a particular migration, we have to set the enableStatistics flag during the create phase. In general, the statistics for a migration are kept in the system for three months.

Retrieve stats for the specified migration

API: /stats/migration/:migration-id Content-Type: JSON Method: POST Header: "X-RStor-Service": "transporter" (can be: transporter, snap or empty)

The :migration-id in the url can be unspecified. In this case the stats for the whole customer will be retrieved.

Field Desc Notes
from Beginning of the time range in Unix Timestamp required
to End of the time range in Unix Timestamp required
aggregateTime The aggregation period in seconds (should be multiple of 60) optional

Example request (request stats for the month of 2021-05)

POST /stats/migration/7684fbee-f67a-4c45-b39f-0993da74c1ce HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]
X-RStor-Service: "transporter"

  {
    "from": 1619830800,
    "to": 1622422799,
    "aggregateTime": 60
  }

Example response

HTTP/1.1 200 OK
Content-Encoding: application/json
Date: [...]

{
    "points": [
        {
            "ts": <timestamp>, // ISO-8601 (2021-05-27T11:43:59+02:00)
            "filesFound": <big integer>,
            "filesTransferred": <big integer>,
            "filesFailed": <big integer>,
            "bytesTransferred": <big integer>,
        },
        ...
    ]
}

Retrieve dashboard view

Retrieve an overview stats for the logged customer. In particular:

API: /stats/dashboard/ Content-Type: JSON Method: POST Header: "X-RStor-Service": "transporter" (can be: transporter, snap or empty)

Example request

POST /stats/dashboard HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]
X-RStor-Service: "transporter"

  {
    "from": 1619830800,
    "to": 1622422799,
  }

Example response

HTTP/1.1 200 OK
Content-Encoding: application/json
Date: [...]

{
    "csp": {
        "rstor": {"egress": <big int>, "ingress": <big int>},
        "s3v4": {"egress": <big int>, "ingress": <big int>},
        "azure": { "egress": <big int>, "ingress": <big int>},
    },
    "totals": {
        "filesFound": <big int>,
        "filesTransferred": <big int>,
        "filesFailed": <big int>,
        "bytesTransferred": <big int>,
    }
}

Current speed

Retrieve the transfer speed in the last m minutes (specified as query paramenter) for the customer.

Notes: * if :migration-id is not specified, we consider all the customer activities * if minutes is not specified, 15min is assumed (default: 15min, max: 60min)

API: /stats/last-speed/:migration-id?minutes=<int> Method: GET Header: "X-RStor-Service": "transporter" (can be: transporter, snap or empty)

Example request (speed in the last 15minutes)

GET /stats/last-speed/?minutes=15 HTTP/1.1
Host: [...]
Authorization: [...]
X-Amz-Content-SHA256: [...]
X-Amz-Date: [...]
X-RStor-Service: "transporter"

Example response

HTTP/1.1 200 OK
Content-Encoding: application/json
Date: [...]

{
    "objects": <big int>, // number of object transferred
    "bytes": <big int>, // number of bytes transferred
    "interval_sec": <int>, // actual interval
}
shell