Direct REST APIs Reveal Key Differences Between Glue and S3 Tables

The Apache Iceberg REST Catalog specification standardizes how clients interact with Iceberg tables via HTTP, enabling tools like PyIceberg and Spark to work seamlessly across different catalog implementations. AWS offers two REST endpoints that comply with this spec: the Glue Iceberg REST endpoint and the S3 Tables Iceberg REST endpoint. While both endpoints follow the same API contract, their design philosophies and practical differences become clear when examining their URL structures, authentication mechanisms, and access control models.

What Defines the Iceberg REST Catalog Standard?

The Iceberg REST Catalog is defined by an OpenAPI specification that standardizes catalog operations as HTTP endpoints. Clients interact with these endpoints using a predictable URL pattern, where the {prefix} segment adapts to the catalog’s internal organization. For example, a request to load a table named ns.table translates to an HTTP GET request to /v1/{prefix}/namespaces/ns/tables/table.

Key behaviors of the REST Catalog spec include:

• Clients begin by querying /v1/config to retrieve endpoint configuration, including the default {prefix} and other runtime settings.
• Table metadata—such as schema, snapshots, and partition specifications—is returned in JSON format within the LoadTable response.
• The {prefix} value acts as a namespace or organizational layer, typically mapping to a catalog hierarchy or table storage location.
• Authentication is not mandated by the spec, but implementations like AWS use SigV4 signing for secure access.

AWS implements this standard through two distinct endpoints, each reflecting a different architectural intent.

Contrasting Glue and S3 Tables REST Endpoints

Despite following the same Iceberg REST Catalog specification, AWS’s two implementations serve fundamentally different purposes.

Glue Iceberg REST endpoint () is designed as a **multi-catalog gateway**, where the {prefix} contains a catalog hierarchy path: /catalogs/{catalog}`. This structure supports multiple logical catalogs under a single endpoint, enabling centralized management of diverse table sets across teams or projects.

S3 Tables Iceberg REST endpoint (), by contrast, treats each table bucket as a **single catalog**, with the {prefix}` set to the URL-encoded ARN of the S3 table bucket. This approach aligns the endpoint directly with a specific storage location, simplifying access control and data management for users who operate within a single bucket.

A side-by-side comparison highlights these differences:

• Endpoint: Glue uses glue..amazonaws.com/iceberg, while S3 Tables uses s3tables..amazonaws.com/iceberg.
• Prefix Structure: Glue’s {prefix} follows /catalogs/{catalog}, whereas S3 Tables uses the bucket ARN.
• Warehouse Parameter: Glue expects a Glue catalog ID, while S3 Tables expects the S3 table bucket ARN.
• SigV4 Service Name: Glue signs requests with the glue service, while S3 Tables uses s3tables.
• Access Control: Glue integrates with IAM and Lake Formation, while S3 Tables enforces s3tables-specific IAM actions.

Under the hood, both endpoints point to the same metadata.json file, but their roles in the data architecture diverge significantly.

Setting Up a Local Test Environment

To explore these differences firsthand, we can create a test environment using the AWS CLI. Begin by defining the region as Tokyo (ap-northeast-1) and the AWS account ID as 123456789012.

Create a dedicated S3 table bucket:

aws s3tables create-table-bucket \
  --name penguin-rest-test \
  --region ap-northeast-1

Define a namespace within that bucket:

aws s3tables create-namespace \
  --table-bucket-arn arn:aws:s3tables:ap-northeast-1:123456789012:bucket/penguin-rest-test \
  --namespace analytics

Create a sample Iceberg table with a basic schema:

aws s3tables create-table \
  --table-bucket-arn arn:aws:s3tables:ap-northeast-1:123456789012:bucket/penguin-rest-test \
  --namespace analytics \
  --name daily_sales \
  --format ICEBERG \
  --metadata '{
    "iceberg": {
      "schema": {
        "fields": [
          {"name": "sales_date", "type": "date", "required": false},
          {"name": "amount", "type": "long", "required": false}
        ]
      }
    }
  }'

These commands set up a clean sandbox for testing the REST API behavior without relying on higher-level clients.

Authenticating to REST Endpoints with SigV4

The Iceberg REST Catalog specification supports OAuth2, but AWS endpoints require SigV4 authentication. This means plain curl requests won’t work—each request must include a cryptographic signature generated using your AWS credentials.

To simplify this process, tools like awscurl automate SigV4 signing. Install it with:

pip install awscurl

When making requests, specify the correct --service flag: use glue for the Glue endpoint and s3tables for the S3 Tables endpoint. This ensures the signature is computed against the right AWS service.

A critical nuance: when passing the {prefix} or warehouse parameter, provide the raw ARN string directly. The awscurl tool automatically URL-encodes query parameters during signing. Pre-encoding the ARN will result in double encoding, causing authentication failures with SignatureDoesNotMatch errors.

Practical Implications for Developers

Understanding these architectural differences is critical when designing data pipelines or selecting a catalog strategy.

Teams that require centralized governance across multiple catalogs will benefit from the Glue endpoint, which offers hierarchical organization and integration with Lake Formation for fine-grained access control.

Projects that operate within a single storage bucket—especially those leveraging S3 Tables for cost efficiency and native compatibility—will find the S3 Tables endpoint simpler to manage, with straightforward access policies and a direct mapping between API calls and storage locations.

As AWS continues to evolve its Iceberg support, these distinctions will shape how developers interact with Iceberg tables in production environments. Choosing the right endpoint depends not just on the Iceberg REST Catalog specification, but on the broader data architecture and access control requirements of your organization.