garage-webui/docs/garage-admin-api.md

Garage Admin API Documentation

Important Note

This document reflects the Garage Web UI's implementation of the Garage Admin API v2.

✅ Full Alignment: As of July 2025, this implementation is fully aligned with the official Garage Admin API v2 specification. All HTTP methods, request formats, and response handling match the official documentation.

• Official HTML Documentation: https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html
• Official JSON Specification: https://garagehq.deuxfleurs.fr/api/garage-admin-v2.json

Overview

The Garage Administration API is a REST API for programmatically managing a Garage cluster, providing complete functionality for cluster management, bucket management, access control, and more. The current version is v2, and the base API address is typically http://localhost:3903.

⚠️ Important Note: This documentation reflects the implementation used by the Garage Web UI project. For the most accurate and up-to-date API specifications, please refer to the official documentation at:

• HTML Documentation: https://garagehq.deuxfleurs.fr/api/garage-admin-v2.html
• JSON Specification: https://garagehq.deuxfleurs.fr/api/garage-admin-v2.json

Current Implementation Status

✅ Production Ready & Fully Compliant: The Garage Web UI implements Garage Admin API v2 with full compliance to the official specification.

Implementation Details

The Garage Web UI utilizes both standard Garage Admin API v2 endpoints and custom backend endpoints:

Standard Garage Admin API v2 Endpoints

• Status: ✅ 18 endpoints implemented
• Compliance: ✅ Fully aligned with official specification
• HTTP Methods: ✅ Match official documentation exactly
• Request/Response Format: ✅ Compliant with official spec

Custom Backend Extensions

• Status: ✅ 9 custom endpoints implemented
• Purpose: Enhanced functionality (authentication, object browsing, file management)
• Integration: Seamlessly integrated with standard API calls

Authentication

Bearer Token Authentication

All API requests must include authentication information in the HTTP header:

Authorization: Bearer <token>

Token Types

1. User-defined Token (Recommended)

   • Can be dynamically created and managed
   • Supports scope limitations
   • Supports setting an expiration time
   • Created using the garage admin-token command

2. Master Token (Deprecated)

   • Specified in the configuration file
   • admin_token: For admin endpoint access
   • metrics_token: For metrics endpoint access

Example of Creating a User-defined Token

garage admin-token create --expires-in 30d \
    --scope ListBuckets,GetBucketInfo,ListKeys,GetKeyInfo,CreateBucket,CreateKey,AllowBucketKey,DenyBucketKey \
    my-token

API Endpoint Categories

1. Cluster Management

Get Cluster Health

• Endpoint: GET /v2/GetClusterHealth
• Description: Returns the global status of the cluster, including the number of connected nodes, healthy storage nodes, partition status, etc.
• Response Example:

{
  "status": "healthy",
  "knownNodes": 3,
  "connectedNodes": 3,
  "storageNodes": 3,
  "storageNodesOk": 3,
  "partitions": 256,
  "partitionsQuorum": 256,
  "partitionsAllOk": 256
}

Get Cluster Status

• Endpoint: GET /v2/GetClusterStatus
• Description: Returns detailed cluster status information, including node information and layout configuration.

Get Cluster Statistics

• Endpoint: GET /v2/GetClusterStatistics
• Description: Gets cluster-level statistics.

Connect Cluster Nodes

• Endpoint: POST /v2/ConnectClusterNodes
• Description: Instructs the current node to connect to other Garage nodes.
• Request Body: An array of node addresses ["<node_id>@<net_address>"]

2. Cluster Layout Management

Get Cluster Layout

• Endpoint: GET /v2/GetClusterLayout
• Description: Returns the current cluster layout configuration and pending changes.

Update Cluster Layout

• Endpoint: POST /v2/UpdateClusterLayout
• Description: Submits cluster layout changes to the staging area.
• Request Body Example:

{
  "roles": [
    {
      "id": "node-id",
      "zone": "zone1",
      "capacity": 100000000000,
      "tags": ["tag1", "tag2"]
    }
  ]
}

Apply Layout Changes

• Endpoint: POST /v2/ApplyClusterLayout
• Description: Applies staged layout changes to the cluster.
• Request Body: {"version": <layout_version>}

Preview Layout Changes

• Endpoint: POST /v2/PreviewClusterLayoutChanges
• Description: Previews the impact of layout changes without actually applying them.

Revert Layout Changes

• Endpoint: POST /v2/RevertClusterLayout
• Description: Clears all staged layout changes.

Get Layout History

• Endpoint: GET /v2/GetClusterLayoutHistory
• Description: Gets the history of cluster layout versions.

3. Bucket Management

List All Buckets

• Endpoint: GET /v2/ListBuckets
• Description: Returns all buckets and their aliases in the cluster.

Get Bucket Information

• Endpoint: GET /v2/GetBucketInfo
• Parameters:
  • id: Bucket ID
  • globalAlias: Global alias
  • search: Search pattern
• Description: Gets detailed bucket information, including permissions, statistics, quotas, etc.

Create Bucket

• Endpoint: POST /v2/CreateBucket
• Request Body Example:

{
  "globalAlias": "my-bucket",
  "localAlias": {
    "accessKeyId": "key-id",
    "alias": "local-name",
    "allow": {
      "read": true,
      "write": true,
      "owner": false
    }
  }
}

Update Bucket

• Endpoint: POST /v2/UpdateBucket/{id}
• Description: Updates a bucket's website configuration and quota settings.
• Request Body Example:

{
  "websiteAccess": {
    "enabled": true,
    "indexDocument": "index.html",
    "errorDocument": "error.html"
  },
  "quotas": {
    "maxSize": 1000000000,
    "maxObjects": 10000
  }
}

Delete Bucket

• Endpoint: POST /v2/DeleteBucket?id={id} (Aligned with Official Specification)
• Method: POST with query parameter
• Purpose: Delete a bucket
• Parameters: Bucket ID in query parameter

Cleanup Incomplete Uploads

• Endpoint: POST /v2/CleanupIncompleteUploads
• Request Body: {"bucketId": "bucket-id", "olderThanSecs": 86400}

Inspect Object

• Endpoint: GET /v2/InspectObject
• Parameters: bucketId, key
• Description: Gets detailed internal status information for an object.

4. Bucket Alias Management

Add Bucket Alias

• Endpoint: POST /v2/AddBucketAlias
• Description: Adds a global or local alias for a bucket.

Remove Bucket Alias

• Endpoint: POST /v2/RemoveBucketAlias
• Description: Removes a bucket's alias.

5. Access Key Management

List Access Keys

• Endpoint: GET /v2/ListKeys
• Description: Returns all API access keys.

Get Key Information

• Endpoint: GET /v2/GetKeyInfo
• Parameters:
  • id: Key ID
  • search: Search pattern
  • showSecretKey: Whether to return the secret key (default is false).

Create Access Key

• Endpoint: POST /v2/CreateKey
• Request Body Example:

{
  "name": "my-key",
  "allow": {
    "createBucket": true
  }
}

Update Access Key

• Endpoint: POST /v2/UpdateKey/{id}
• Description: Updates a key's name, permissions, and expiration time.

Delete Access Key

• Endpoint: POST /v2/DeleteKey?id={id} (Aligned with Official Specification)
• Method: POST with query parameter
• Purpose: Delete an access key
• Parameters: Key ID in query parameter

Import Access Key

• Endpoint: POST /v2/ImportKey
• Description: Imports an existing access key (only for migration and backup recovery).

6. Permission Management

Grant Permission

• Endpoint: POST /v2/AllowBucketKey
• Description: Grants a key permission to perform operations on a bucket.
• Request Body Example:

{
  "bucketId": "bucket-id",
  "accessKeyId": "key-id",
  "permissions": {
    "read": true,
    "write": true,
    "owner": false
  }
}

Deny Permission

• Endpoint: POST /v2/DenyBucketKey
• Description: Removes a key's permission to perform operations on a bucket.

7. Admin API Token Management

List Admin Tokens

• Endpoint: GET /v2/ListAdminTokens

Get Token Information

• Endpoint: GET /v2/GetAdminTokenInfo
• Parameters: id or search

Get Current Token Information

• Endpoint: GET /v2/GetCurrentAdminTokenInfo

Create Admin Token

• Endpoint: POST /v2/CreateAdminToken
• Request Body Example:

{
  "name": "my-admin-token",
  "expiration": "2025-12-31T23:59:59Z",
  "scope": ["ListBuckets", "GetBucketInfo", "CreateBucket"]
}

Update Admin Token

• Endpoint: POST /v2/UpdateAdminToken/{id}

Delete Admin Token

• Endpoint: POST /v2/DeleteAdminToken/{id}

8. Node Management

Get Node Information

• Endpoint: GET /v2/GetNodeInfo/{node}
• Parameters: node - Node ID, * (all nodes), or self (current node)

Get Node Statistics

• Endpoint: GET /v2/GetNodeStatistics/{node}

Create Metadata Snapshot

• Endpoint: POST /v2/CreateMetadataSnapshot/{node}

Launch Repair Operation

• Endpoint: POST /v2/LaunchRepairOperation/{node}
• Repair Types: tables, blocks, versions, multipartUploads, blockRefs, blockRc, rebalance, aliases

9. Worker Process Management

List Workers

• Endpoint: POST /v2/ListWorkers/{node}

Get Worker Information

• Endpoint: POST /v2/GetWorkerInfo/{node}

Get Worker Variable

• Endpoint: POST /v2/GetWorkerVariable/{node}

Set Worker Variable

• Endpoint: POST /v2/SetWorkerVariable/{node}

10. Block Management

Get Block Information

• Endpoint: POST /v2/GetBlockInfo/{node}
• Request Body: {"blockHash": "hash-value"}

List Block Errors

• Endpoint: GET /v2/ListBlockErrors/{node}

Retry Block Resync

• Endpoint: POST /v2/RetryBlockResync/{node}

Purge Blocks

• Endpoint: POST /v2/PurgeBlocks/{node}
• Warning: This operation permanently deletes all objects that reference these blocks.

11. Special Endpoints

Health Check

• Endpoint: GET /health
• Authentication: None required
• Description: Quick health check, returns 200 if the service is available.

Prometheus Metrics

• Endpoint: GET /metrics
• Authentication: Optional (using metrics_token)
• Description: Returns monitoring metrics in Prometheus format.

On-Demand TLS Check

• Endpoint: GET /check?domain=<domain>
• Authentication: None required
• Description: Used for on-demand TLS certificate validation by reverse proxies (like Caddy).

Usage Example

Using curl

# Get cluster health status
curl -H 'Authorization: Bearer YOUR_TOKEN' \
     http://localhost:3903/v2/GetClusterHealth

# Create a bucket
curl -X POST \
     -H 'Authorization: Bearer YOUR_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"globalAlias": "my-bucket"}' \
     http://localhost:3903/v2/CreateBucket

# List all buckets
curl -H 'Authorization: Bearer YOUR_TOKEN' \
     http://localhost:3903/v2/ListBuckets

Using the Garage CLI

# Call via internal RPC (no authentication required)
garage json-api GetClusterHealth

# Call with parameters
garage json-api GetBucketInfo '{"globalAlias": "my-bucket"}'

# Read parameters from standard input
garage json-api CreateBucket -
{"globalAlias": "test-bucket"}
<EOF>

Error Handling

The API uses standard HTTP status codes:

• 200 OK - Request successful
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Authentication failed
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 500 Internal Server Error - Internal server error

Error responses typically include detailed error information:

{
  "error": "Bucket not found",
  "code": "BucketNotFound"
}

Permission Scopes

Admin tokens can be restricted to specific API endpoints:

• * - Allows all endpoints
• ListBuckets - List buckets
• GetBucketInfo - Get bucket information
• CreateBucket - Create a bucket
• ListKeys - List access keys
• CreateKey - Create an access key
• AllowBucketKey - Grant permissions
• DenyBucketKey - Deny permissions
• Metrics - Access the metrics endpoint

Best Practices

1. Use User-defined Tokens: Avoid using the master token from the configuration file.
2. Set Appropriate Scopes: Grant only necessary permissions.
3. Set Expiration Times: Rotate tokens periodically.
4. Monitor API Usage: Monitor API calls via the /metrics endpoint.
5. Handle Errors: Properly handle various error conditions.
6. Bulk Operations: For a large number of operations, consider using bulk APIs or scripts.

Version History

• v0 - First introduced in Garage v0.7.2 (deprecated)
• v1 - Introduced in Garage v0.9.0 (deprecated, still supported for backward compatibility)
• v2 - Introduced in Garage v2.0.0 (current version, actively used by Garage Web UI)

Migration Notes:

• The Garage Web UI has successfully migrated from v1 to v2 API
• All core functionality now utilizes v2 endpoints for improved performance and feature access
• Legacy v1 endpoints remain available for backward compatibility but are not recommended for new implementations

Related Links

• Garage Official Documentation
• OpenAPI Specification (HTML)
• OpenAPI Specification (JSON)
• Garage Source Code