S3 API

Graphon Storage speaks the Amazon S3 API. Point an S3 tool or SDK at your workspace S3 endpoint, and sign with an API key from that workspace. Each operation below has its own page with its parameters, responses, errors, and samples.

Connection

Replace wspq7ws2np5l8z4 in every example with your workspace ID. The key must belong to the workspace in the hostname. The bare storage host serves the JSON API only. Use the workspace host for S3, including public object links and presigned requests.

us-east-1 is only the signing region. Your data stays in the location that you chose for the bucket. A key covers every bucket in its workspace, and each operation needs the role on its page. See Authentication & keys for how to get the credentials and presign a URL.

Bucket names and rename

Names are unique within one workspace and are case-sensitive. Use 1–255 ASCII letters, digits, periods, underscores, or hyphens. The exact names . and .. are invalid. Another workspace can use the same name.

Rename through the JSON API or graphon buckets rename. S3 has no RenameBucket operation. The bucket ID and data stay unchanged. Update name-based URLs and client settings after a rename. See Renaming buckets.

Set up a client

The aws CLI reads the graphon profile. The SDK samples read the key from GRAPHON_API_KEY. Each operation page uses the same setup.

# Replace wspq7ws2np5l8z4 with your workspace ID.
# ~/.aws/config
[profile graphon]
credential_process = graphon s3-credentials --format process
endpoint_url = https://wspq7ws2np5l8z4.storage.beta.graphon.sh
region = us-east-1
s3 =
  addressing_style = path

aws s3 ls --profile graphon
aws s3 cp ./checkout-timeout.json s3://support-tickets/incidents/ --profile graphon

# Replace wspq7ws2np5l8z4 with your workspace ID.
import os

import boto3
from botocore.config import Config

api_key = os.environ["GRAPHON_API_KEY"]
access_key_id = api_key.split("_", 1)[1].split(".")[0]

s3 = boto3.client(
    "s3",
    endpoint_url="https://wspq7ws2np5l8z4.storage.beta.graphon.sh",
    region_name="us-east-1",
    aws_access_key_id=access_key_id,
    aws_secret_access_key=api_key,
    config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
)
print(s3.list_objects_v2(Bucket="support-tickets", Prefix="incidents/"))

import { ListObjectsV2Command } from '@aws-sdk/client-s3';

// Replace wspq7ws2np5l8z4 with your workspace ID.
import { S3Client } from '@aws-sdk/client-s3';

const apiKey = process.env.GRAPHON_API_KEY;
if (!apiKey) throw new Error('Set GRAPHON_API_KEY.');
const accessKeyId = apiKey.split('_')[1].split('.')[0];

const s3 = new S3Client({
  endpoint: 'https://wspq7ws2np5l8z4.storage.beta.graphon.sh',
  region: 'us-east-1',
  forcePathStyle: true,
  credentials: { accessKeyId, secretAccessKey: apiKey },
});

console.log(await s3.send(new ListObjectsV2Command({
  Bucket: 'support-tickets',
  Prefix: 'incidents/',
})));

# Replace wspq7ws2np5l8z4 with your workspace ID.
# ~/.config/rclone/rclone.conf
[graphon]
type = s3
provider = Other
endpoint = https://wspq7ws2np5l8z4.storage.beta.graphon.sh
region = us-east-1
force_path_style = true
env_auth = true

# Then, with GRAPHON_API_KEY set, this sets AWS_ACCESS_KEY_ID and
# AWS_SECRET_ACCESS_KEY for rclone:
# eval "$(graphon s3-credentials)"
# rclone ls graphon:support-tickets

Operations

Storage supports these operations. A partial operation supports the common case. Its page lists what differs from Amazon S3.

Common errors

An error has an XML body with a Code and a Message. Every response has an x-amz-request-id header. Send it to support when you report a problem. Any request can get these errors. Each operation page lists its own errors.

Browser requests

Storage answers a CORS preflight (OPTIONS) on any S3 path with 204. It allows every origin and header, and the GET, PUT, POST, DELETE, and HEAD methods. A preflight reads and changes nothing. A browser can use a presigned URL, or read an object from a public-read bucket with no signature.

Not supported

These requests return 501 NotImplemented. An S3 request to the bare storage host returns 404 with a JSON error. Storage ignores the other S3 features that it does not support. Each operation page names the parameters that it ignores.