API Reference

Strix exposes two APIs:

S3 API (port 9000) - Amazon S3-compatible API for object storage operations
Admin API (port 9001) - REST API for server administration

S3 API

The S3 API is compatible with AWS SDKs and S3 clients. All requests must be signed using AWS Signature Version 4.

Authentication

All S3 API requests must include AWS Signature V4 authentication headers:

Authorization: AWS4-HMAC-SHA256 Credential=.../s3/aws4_request, SignedHeaders=..., Signature=...
X-Amz-Date: 20240101T000000Z
X-Amz-Content-Sha256: <payload-hash>

Bucket Operations

Create Bucket

PUT /{bucket} HTTP/1.1
Host: localhost:9000

Response: 200 OK

Delete Bucket

DELETE /{bucket} HTTP/1.1
Host: localhost:9000

Response: 204 No Content

Error: 409 Conflict if bucket is not empty

List Buckets

GET / HTTP/1.1
Host: localhost:9000

Response:

<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Owner>
    <ID>owner-id</ID>
    <DisplayName>owner</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <Name>my-bucket</Name>
      <CreationDate>2024-01-01T00:00:00.000Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

Head Bucket

HEAD /{bucket} HTTP/1.1
Host: localhost:9000

Response: 200 OK if bucket exists, 404 Not Found otherwise

Object Operations

Put Object

PUT /{bucket}/{key} HTTP/1.1
Host: localhost:9000
Content-Length: <size>
Content-Type: <mime-type>

<binary-data>

Response Headers:

ETag: "<md5-hash>"

Get Object

GET /{bucket}/{key} HTTP/1.1
Host: localhost:9000

Optional Headers:

Range: bytes=0-1023 - Request partial content

Response Headers:

Content-Length: <size>
Content-Type: <mime-type>
ETag: "<md5-hash>"
Last-Modified: <date>

Delete Object

DELETE /{bucket}/{key} HTTP/1.1
Host: localhost:9000

Response: 204 No Content

Head Object

HEAD /{bucket}/{key} HTTP/1.1
Host: localhost:9000

Response Headers:

Content-Length: <size>
Content-Type: <mime-type>
ETag: "<md5-hash>"
Last-Modified: <date>

List Objects (V2)

GET /{bucket}?list-type=2 HTTP/1.1
Host: localhost:9000

Query Parameters:

prefix - Filter by prefix
delimiter - Group by delimiter (typically /)
max-keys - Maximum number of keys (default: 1000)
continuation-token - Pagination token

Response:

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
  <Name>my-bucket</Name>
  <Prefix></Prefix>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>file.txt</Key>
    <LastModified>2024-01-01T00:00:00.000Z</LastModified>
    <ETag>"abc123"</ETag>
    <Size>1024</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <CommonPrefixes>
    <Prefix>folder/</Prefix>
  </CommonPrefixes>
</ListBucketResult>

Copy Object

PUT /{bucket}/{key} HTTP/1.1
Host: localhost:9000
X-Amz-Copy-Source: /source-bucket/source-key

Response:

<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
  <LastModified>2024-01-01T00:00:00.000Z</LastModified>
  <ETag>"abc123"</ETag>
</CopyObjectResult>

Delete Objects (Batch)

POST /{bucket}?delete HTTP/1.1
Host: localhost:9000
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<Delete>
  <Object>
    <Key>file1.txt</Key>
  </Object>
  <Object>
    <Key>file2.txt</Key>
  </Object>
</Delete>

Multipart Upload Operations

Initiate Multipart Upload

POST /{bucket}/{key}?uploads HTTP/1.1
Host: localhost:9000

Response:

<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult>
  <Bucket>my-bucket</Bucket>
  <Key>large-file.zip</Key>
  <UploadId>abc123</UploadId>
</InitiateMultipartUploadResult>

Upload Part

PUT /{bucket}/{key}?partNumber=1&uploadId=abc123 HTTP/1.1
Host: localhost:9000
Content-Length: <part-size>

<binary-data>

Response Headers:

ETag: "<part-etag>"

Complete Multipart Upload

POST /{bucket}/{key}?uploadId=abc123 HTTP/1.1
Host: localhost:9000

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUpload>
  <Part>
    <PartNumber>1</PartNumber>
    <ETag>"part1-etag"</ETag>
  </Part>
  <Part>
    <PartNumber>2</PartNumber>
    <ETag>"part2-etag"</ETag>
  </Part>
</CompleteMultipartUpload>

Abort Multipart Upload

DELETE /{bucket}/{key}?uploadId=abc123 HTTP/1.1
Host: localhost:9000

Admin API

The Admin API is a REST API for managing the Strix server. All endpoints are under /api/v1/.

Server Information

Get Server Info

GET /api/v1/info HTTP/1.1
Host: localhost:9001

Response:

{
  "version": "0.1.0",
  "commit": "abc123",
  "mode": "standalone",
  "uptime": 3600,
  "region": "us-east-1"
}

Health Check

GET /api/v1/health HTTP/1.1
Host: localhost:9001

Response: 200 OK

User Management

List Users

GET /api/v1/users HTTP/1.1
Host: localhost:9001

Response:

{
  "users": [
    {
      "username": "alice",
      "arn": "arn:aws:iam:::user/alice",
      "created_at": "2024-01-01T00:00:00Z",
      "status": "active",
      "policies": ["ReadWriteAccess"]
    }
  ]
}

Create User

POST /api/v1/users HTTP/1.1
Host: localhost:9001
Content-Type: application/json

{
  "username": "alice"
}

Response:

{
  "user": {
    "username": "alice",
    "arn": "arn:aws:iam:::user/alice",
    "created_at": "2024-01-01T00:00:00Z",
    "status": "active"
  },
  "access_key": {
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "username": "alice",
    "created_at": "2024-01-01T00:00:00Z",
    "status": "active"
  }
}

Get User

GET /api/v1/users/{username} HTTP/1.1
Host: localhost:9001

Delete User

DELETE /api/v1/users/{username} HTTP/1.1
Host: localhost:9001

Response: 204 No Content

Access Key Management

List Access Keys

GET /api/v1/users/{username}/access-keys HTTP/1.1
Host: localhost:9001

Response:

{
  "access_keys": [
    {
      "access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "username": "alice",
      "created_at": "2024-01-01T00:00:00Z",
      "status": "active"
    }
  ]
}

Create Access Key

POST /api/v1/users/{username}/access-keys HTTP/1.1
Host: localhost:9001

Response:

{
  "access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "username": "alice",
  "created_at": "2024-01-01T00:00:00Z",
  "status": "active"
}

Delete Access Key

DELETE /api/v1/access-keys/{access_key_id} HTTP/1.1
Host: localhost:9001

Policy Management

List User Policies

GET /api/v1/users/{username}/policies HTTP/1.1
Host: localhost:9001

Attach User Policy

POST /api/v1/users/{username}/policies HTTP/1.1
Host: localhost:9001
Content-Type: application/json

{
  "policy": {
    "name": "MyPolicy",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": ["s3:GetObject", "s3:PutObject"],
        "Resource": ["arn:aws:s3:::my-bucket/*"]
      }
    ]
  }
}

Detach User Policy

DELETE /api/v1/users/{username}/policies/{policy_name} HTTP/1.1
Host: localhost:9001

Bucket Management

List Buckets

GET /api/v1/buckets HTTP/1.1
Host: localhost:9001

Create Bucket

POST /api/v1/buckets HTTP/1.1
Host: localhost:9001
Content-Type: application/json

{
  "name": "my-bucket"
}

Delete Bucket

DELETE /api/v1/buckets/{name} HTTP/1.1
Host: localhost:9001

Bucket Policies

Get Bucket Policy

GET /api/v1/buckets/{bucket}/policy HTTP/1.1
Host: localhost:9001

Response:

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

Set Bucket Policy

PUT /api/v1/buckets/{bucket}/policy HTTP/1.1
Host: localhost:9001
Content-Type: application/json

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

Delete Bucket Policy

DELETE /api/v1/buckets/{bucket}/policy HTTP/1.1
Host: localhost:9001

Object Management

List Objects

GET /api/v1/buckets/{bucket}/objects?prefix=folder/&delimiter=/ HTTP/1.1
Host: localhost:9001

Delete Object

DELETE /api/v1/buckets/{bucket}/objects/{key} HTTP/1.1
Host: localhost:9001

Delete Multiple Objects

DELETE /api/v1/buckets/{bucket}/objects HTTP/1.1
Host: localhost:9001
Content-Type: application/json

{
  "keys": ["file1.txt", "file2.txt"]
}

Pre-signed URLs

Generate Pre-signed URL

POST /api/v1/presign HTTP/1.1
Host: localhost:9001
Content-Type: application/json

{
  "bucket": "my-bucket",
  "key": "file.txt",
  "method": "GET",
  "expires_in": 3600
}

Response:

{
  "url": "http://localhost:9000/my-bucket/file.txt?X-Amz-Algorithm=...",
  "expires_in": 3600,
  "method": "GET"
}

Storage Usage

Get Storage Usage

GET /api/v1/usage HTTP/1.1
Host: localhost:9001

Response:

{
  "buckets": [
    {
      "name": "my-bucket",
      "created_at": "2024-01-01T00:00:00Z",
      "object_count": 100,
      "total_size": 1073741824
    }
  ],
  "total_buckets": 1,
  "total_objects": 100,
  "total_size": 1073741824
}

Error Responses

S3 API Errors

S3 API errors are returned as XML:

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchBucket</Code>
  <Message>The specified bucket does not exist</Message>
  <Resource>/my-bucket</Resource>
  <RequestId>abc123</RequestId>
</Error>

Common error codes:

NoSuchBucket - Bucket does not exist
NoSuchKey - Object does not exist
BucketAlreadyExists - Bucket name is taken
BucketNotEmpty - Cannot delete non-empty bucket
AccessDenied - Permission denied
InvalidArgument - Invalid request parameter
SignatureDoesNotMatch - Invalid signature

Admin API Errors

Admin API errors are returned as JSON:

{
  "error": "User not found",
  "message": "The user 'alice' does not exist"
}

HTTP status codes:

400 Bad Request - Invalid request
401 Unauthorized - Authentication required
403 Forbidden - Permission denied
404 Not Found - Resource not found
409 Conflict - Resource conflict (e.g., bucket not empty)
500 Internal Server Error - Server error

FilesExpand file tree

api-reference.md

Latest commit

History

api-reference.md

File metadata and controls

API Reference

S3 API

Authentication

Bucket Operations

Create Bucket

Delete Bucket

List Buckets

Head Bucket

Object Operations

Put Object

Get Object

Delete Object

Head Object

List Objects (V2)

Copy Object

Delete Objects (Batch)

Multipart Upload Operations

Initiate Multipart Upload

Upload Part

Complete Multipart Upload

Abort Multipart Upload

Admin API

Server Information

Get Server Info

Health Check

User Management

List Users

Create User

Get User

Delete User

Access Key Management

List Access Keys

Create Access Key

Delete Access Key

Policy Management

List User Policies

Attach User Policy

Detach User Policy

Bucket Management

List Buckets

Create Bucket

Delete Bucket

Bucket Policies

Get Bucket Policy

Set Bucket Policy

Delete Bucket Policy

Object Management

List Objects

Delete Object

Delete Multiple Objects

Pre-signed URLs

Generate Pre-signed URL

Storage Usage

Get Storage Usage

Error Responses

S3 API Errors

Admin API Errors