Quickstart

By following this tutorial, you will set up the mechanisms that allow you to authenticate, create buckets and manage your objects.

The complete reference of the Object Storage API is available in the Scalar OpenAPI documentation.

1. Obtaining a key pair (access and secret)

First, you must have an AK/SK key pair (Access Key/Secret Key) that allows you to authenticate against the Numspot Object Storage API.

To begin, you will need a token.

With your token, you must exchange it for an AK/SK key pair, using the "convert" endpoint.

## request
curl 'https://api.{{region}}.numspot.com/iam/token/convert' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --data '{
  "token": "…"
}'

You will then obtain the AK/SK:

## response
{
  "ak": "…",
  "sk": "…"
}

warning

The key pair is valid for 24 hours.

2. Create a bucket

To create a bucket, use the mb command following this syntax:

## request
aws s3 mb s3://BUCKET_NAME \
    --profile YOUR_PROFILE \
    --debug \
    --endpoint https://objectstorage.{{region}}.numspot.com/spaces/{{spaceId}}

This command contains the following options that you must specify:

• s3://BUCKET_NAME: The name you want to give to your bucket, according to the corresponding naming rules.
• endpoint: The endpoint corresponding to the region to which you want to send the request.
• (optional) profile: The named profile you want to use, created during the configuration of the AWS CLI (Command Line Interface). To find out more, see Install and configure the AWS CLI.
• (optional) debug: If included, returns a detailed report of the operation. This option is useful for analyzing and troubleshooting the issues you may encounter.

The bucket is created.

3. Upload an object

To upload a local object into a bucket, use the cp command following this syntax:

## request
aws s3 cp LOCAL_PATH/OBJECT_TO_UPLOAD s3://BUCKET_NAME/PATH \
   --profile YOUR_PROFILE \
   --debug \
   --endpoint https://objectstorage.{{region}}.numspot.com/spaces/{{spaceId}}

This command contains the following options that you must specify:

• LOCAL_PATH/OBJECT_TO_UPLOAD: The local path of the object you want to upload into the bucket.
• s3://BUCKET_NAME/PATH: The access path to the object you want to upload into the bucket.
• endpoint: The endpoint corresponding to the region to which you want to send the request.
• (optional) profile: The named profile you want to use, created during the configuration of the AWS CLI. To find out more, see Install and configure the AWS CLI.
• (optional) debug: If included, returns a detailed report of the operation. This option is useful for analyzing and troubleshooting the issues you may encounter.

4. Download an object from a bucket

To download an object from a bucket, use the cp command following this syntax:

## request
aws s3 cp s3://YOUR_BUCKET/YOUR_OBJECT PATH/TO/FILE \
    --profile YOUR_PROFILE \
    --debug \
    --endpoint https://objectstorage.{{region}}.numspot.com/spaces/{{spaceId}}

This command contains the following options that you must specify:

• s3://YOUR_BUCKET/YOUR_OBJECT: The name of the bucket and the name of the object it contains.
• PATH/TO/FILE: The path to the location where you want the object to be downloaded.
• endpoint: The endpoint corresponding to the region to which you want to send the request.
• (optional) profile: The named profile you want to use, created during the configuration of the AWS CLI. To find out more, see Install and configure the AWS CLI.
• (optional) debug: If included, returns a detailed report of the operation. This option is useful for analyzing and troubleshooting the issues you may encounter.

5. Delete objects from a bucket

To delete several objects from a bucket, use the rm command following this syntax:

## request
aws s3 rm s3://YOUR_BUCKET/YOUR_OBJECT \
    --profile YOUR_PROFILE \
    --debug \
    --endpoint https://objectstorage.{{region}}.numspot.com/spaces/{{spaceId}}

This command contains the following options that you must specify:

• s3://YOUR_BUCKET/YOUR_OBJECT: The path to the object you want to delete from the bucket.

  info

  You can specify the version ID of an object following this syntax: s3://YOUR_BUCKET/YOUR_OBJECT?versionID=<YOUR_VERSION_ID>.

• endpoint: The endpoint corresponding to the region to which you want to send the request.

• (optional) profile: The named profile you want to use, created during the configuration of the AWS CLI. To find out more, see Install and configure the AWS CLI.

• (optional) debug: If included, returns a detailed report of the operation. This option is useful for analyzing and troubleshooting the issues you may encounter.

6. Delete a bucket

To delete a bucket, use the rb command following this syntax:

## request
aws s3 rb s3://YOUR_BUCKET \
    --profile YOUR_PROFILE \
    --debug \
    --force \
    --endpoint https://objectstorage.{{region}}.numspot.com/spaces/{{spaceId}}

This command contains the following options that you must specify:

• s3://YOUR_BUCKET: The name of the bucket you want to delete.

• endpoint: The endpoint corresponding to the region to which you want to send the request.

• (optional) profile: The named profile you want to use, created during the configuration of the AWS CLI. To find out more, see Install and configure the AWS CLI.

• (optional) debug: If included, returns a detailed report of the operation. This option is useful for analyzing and troubleshooting the issues you may encounter.

• (optional) force: Deletes all the objects contained in the bucket as well as the bucket itself.

  warning

  The command fails if the bucket contains versioned objects. To delete versioned objects, see Delete objects from a bucket.