14-bucket-explorers

Bucket Explorer Management Endpoints

Note: Utility resources (terminals, bucket explorers, db monitors) share common patterns. See 11-utility-resources.md for a consolidated overview; this file focuses on bucket-explorer specifics.

Bucket explorers are resources that can be connected to storage buckets to browse and explore their contents. Similar to terminals that connect to instances, bucket explorers provide a way to interact with S3 buckets.

Create Bucket Explorer

POST /api/:projectSlug/:environmentSlug/bucket-explorers - Create a new bucket explorer resource and S3 storage bucket

Description: The name provided will be used directly as the S3 bucket name. The endpoint will automatically create the S3 bucket and connect it to the bucket explorer. Important:

The name must be a valid S3 bucket name (3-63 characters, lowercase, alphanumeric, hyphens, periods)
Bucket names must be globally unique across all AWS accounts
The endpoint will automatically create the S3 bucket and connect it to the bucket explorer

Request Body:

{
  "name": "my-bucket-name",  // Will be used as S3 bucket name (must follow AWS S3 naming rules)
  "region": "us-east-1",     // Optional, defaults to connection region
  "positionX": 100,          // Optional, canvas X coordinate
  "positionY": 200           // Optional, canvas Y coordinate
}

S3 Bucket Naming Rules:

Must be 3 to 63 characters long
Must begin and end with a letter or number
Can contain lowercase letters (a-z), numbers (0-9), periods (.), and hyphens (-)
Cannot contain consecutive periods (..)
Cannot be formatted as an IP address (e.g., 192.168.1.1)
Cannot start with “xn—” or end with “-s3alias”
Must be globally unique across all AWS accounts

Example:

curl -X POST "https://api.gateways.app/api/codepanel/master/bucket-explorers" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-bucket-name",
    "region": "us-east-1",
    "positionX": 300,
    "positionY": 400
  }'

Example Response:

{
  "message": "Bucket explorer and S3 bucket created successfully",
  "data": {
    "id": 1,
    "name": "my-bucket-name",
    "bucketName": "my-bucket-name",
    "status": "inactive",
    "position": {
      "x": 300,
      "y": 400
    },
    "storageBucket": {
      "id": 1,
      "name": "my-bucket-name",
      "awsBucketName": "my-bucket-name",
      "region": "us-east-1"
    },
    "project": {
      "id": 1,
      "slug": "codepanel",
      "name": "CodePanel"
    },
    "environment": {
      "id": 1,
      "slug": "master",
      "name": "master"
    },
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Error Response (Invalid bucket name):

{
  "error": "Invalid bucket name",
  "message": "Bucket name must be at least 3 characters long"
}

Error Response (Bucket already exists):

{
  "error": "Bucket name already exists",
  "message": "A bucket with name \"my-bucket-name\" already exists in AWS. Bucket names must be globally unique."
}

List Bucket Explorers

GET /api/:projectSlug/:environmentSlug/bucket-explorers - List all bucket explorers for a project environment

Example:

curl "https://api.gateways.app/api/codepanel/master/bucket-explorers" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response:

{
  "message": "Bucket explorers retrieved successfully",
  "data": [
    {
      "id": 1,
      "name": "My Bucket Explorer",
      "status": "inactive",
      "position": {
        "x": 300,
        "y": 400
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": 2,
      "name": "Backup Explorer",
      "status": "active",
      "position": {
        "x": 500,
        "y": 600
      },
      "createdAt": "2024-01-15T11:00:00.000Z",
      "updatedAt": "2024-01-15T11:00:00.000Z"
    }
  ]
}

Get Bucket Explorer Details

GET /api/:projectSlug/:environmentSlug/bucket-explorers/:explorerId - Get details of a specific bucket explorer

Example:

curl "https://api.gateways.app/api/codepanel/master/bucket-explorers/1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response:

{
  "message": "Bucket explorer retrieved successfully",
  "data": {
    "id": 1,
    "name": "My Bucket Explorer",
    "status": "inactive",
    "position": {
      "x": 300,
      "y": 400
    },
    "project": {
      "id": 1,
      "slug": "codepanel",
      "name": "CodePanel"
    },
    "environment": {
      "id": 1,
      "slug": "master",
      "name": "master"
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Update Bucket Explorer

PATCH /api/:projectSlug/:environmentSlug/bucket-explorers/:explorerId - Update a bucket explorer

Request Body:

{
  "name": "Updated Explorer Name",  // Optional
  "status": "active",  // Optional: active, inactive, connecting, error
  "positionX": 350,  // Optional
  "positionY": 450   // Optional
}

Example:

curl -X PATCH "https://api.gateways.app/api/codepanel/master/bucket-explorers/1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Explorer Name",
    "status": "active",
    "positionX": 350,
    "positionY": 450
  }'

Example Response:

{
  "message": "Bucket explorer updated successfully",
  "data": {
    "id": 1,
    "name": "Updated Explorer Name",
    "status": "active",
    "position": {
      "x": 350,
      "y": 450
    },
    "updatedAt": "2024-01-15T12:00:00.000Z"
  }
}

Delete Bucket Explorer

Bucket explorer deletion is performed only via the unified resources API:

DELETE /api/:projectSlug/:environmentSlug/resources/:resourceId

Use the bucket explorer’s database ID. The service removes all resource connections, then soft-deletes the resource. See Resources API — Delete Resource by ID. Example:

curl -X DELETE "https://api.gateways.app/api/codepanel/master/resources/1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Connecting Bucket Explorers to Storage Buckets

Bucket explorers can be connected to storage buckets using the Resource Connections API. This allows the bucket explorer to browse and interact with the contents of the connected storage bucket. Example: Connect bucket explorer to a storage bucket

curl -X POST "https://api.gateways.app/api/codepanel/master/resource-connections" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceResourceType": "bucket_explorer",
    "sourceResourceId": 1,
    "targetResourceType": "storage_bucket",
    "targetResourceId": 1
  }'

See the Resource Connections documentation for more details on connecting resources.

Status Values

Bucket explorers have the following status values:

inactive - Default status when created
active - Explorer is active and connected
connecting - Currently establishing connection
error - Connection error occurred

​Bucket Explorer Management Endpoints

​Create Bucket Explorer

​List Bucket Explorers

​Get Bucket Explorer Details

​Update Bucket Explorer

​Delete Bucket Explorer

​Connecting Bucket Explorers to Storage Buckets

​Status Values

Bucket Explorer Management Endpoints

Create Bucket Explorer

List Bucket Explorers

Get Bucket Explorer Details

Update Bucket Explorer

Delete Bucket Explorer

Connecting Bucket Explorers to Storage Buckets

Status Values