REST catalog APIs. More...

Namespaces
namespace	auth
	REST catalog authentication APIs.

Classes
struct	CaseInsensitiveHeaderLess
	Case-insensitive ordering for HTTP header names. More...

struct	CatalogConfig
	Server-provided configuration for the catalog. More...

struct	CommitTableRequest
	Request to commit changes to a table. More...

struct	CommitTableResponse
	Response from committing changes to a table. More...

class	ConfigErrorHandler
	Error handler for the catalog config endpoint. More...

struct	CreateNamespaceRequest
	Request to create a namespace. More...

struct	CreateNamespaceResponse
	Response body after creating a namespace. More...

class	CreateTableErrorHandler
	Table create commit operation error handler. More...

struct	CreateTableRequest
	Request to create a table. More...

class	DefaultErrorHandler
	Default error handler for REST API responses. More...

class	DropNamespaceErrorHandler
	Error handler for drop namespace operations. More...

class	Endpoint
	An Endpoint is an immutable value object identifying a specific REST API operation. It consists of: More...

class	ErrorHandler
	Error handler interface for processing REST API error responses. Maps HTTP status codes to appropriate ErrorKind values following the Iceberg REST specification. More...

struct	ErrorResponse
	JSON error payload returned in a response with further details on the error. More...

struct	FetchPlanningResultResponse
	Response from polling an asynchronous scan plan, including current status and available scan tasks. More...

struct	FetchScanTasksRequest
	Request to fetch the scan tasks for a given plan task token. More...

struct	FetchScanTasksResponse
	Response containing the file scan tasks for a given plan task token. More...

struct	GetNamespaceResponse
	Response body for loading namespace properties. More...

class	HttpClient
	HTTP client for making requests to Iceberg REST Catalog API. More...

struct	HttpRequest
	An outgoing HTTP request. Mirrors Java's HttpRequest so signing implementations like SigV4 see method, url, headers, and body together. More...

class	HttpResponse
	A simple wrapper for cpr::Response. More...

struct	ListNamespacesResponse
	Response body for listing namespaces. More...

struct	ListTablesResponse
	Response body for listing tables in a namespace. More...

struct	LoadTableResult
	Result body for table create/load/register APIs. More...

class	NamespaceErrorHandler
	Namespace-specific error handler for create/read/update operations. More...

class	OAuthErrorHandler
	OAuth token endpoint error handler. More...

struct	OAuthTokenResponse
	Response from an OAuth2 token endpoint. More...

class	PlanErrorHandler
	Plan operation error handler. More...

struct	PlanTableScanRequest
	Request to initiate a server-side scan planning operation. More...

struct	PlanTableScanResponse
	Response from initiating a scan planning operation, including plan status and initial scan tasks. More...

class	PlanTaskErrorHandler
	Fetch scan tasks operation error handler. More...

struct	RegisterTableRequest
	Request to register a table. More...

struct	RenameTableRequest
	Request to rename a table. More...

class	ResourcePaths
	Resource path builder for Iceberg REST catalog endpoints. More...

class	RestCatalog
	Session-aware REST catalog root. More...

class	RestCatalogProperties
	Configuration class for a REST Catalog. More...

class	TableCommitErrorHandler
	Table commit operation error handler. More...

class	TableErrorHandler
	Table-level error handler. More...

struct	UpdateNamespacePropertiesRequest
	Update or delete namespace properties request. More...

struct	UpdateNamespacePropertiesResponse
	Response body after updating namespace properties. More...

class	ViewCommitErrorHandler
	View commit operation error handler. More...

class	ViewErrorHandler
	View-level error handler. More...

Typedefs
using	HttpHeaders = std::map< std::string, std::string, CaseInsensitiveHeaderLess >
	Single-value HTTP headers with case-insensitive names.

using	PageToken = std::string
	An opaque token that allows clients to make use of pagination for list APIs.

using	CreateTableResponse = LoadTableResult
	Alias of LoadTableResult used as the body of CreateTableResponse.

using	LoadTableResponse = LoadTableResult
	Alias of LoadTableResult used as the body of LoadTableResponse.

Enumerations
enum class	SnapshotMode : uint8_t { kAll , kRefs }
	Snapshot loading mode for REST catalog.

enum class	HttpMethod : uint8_t { kGet , kPost , kPut , kDelete , kHead }
	HTTP method enumeration.

enum class	PlanStatus { kSubmitted , kCompleted , kCancelled , kFailed }
	Status of a REST server-side scan planning operation.

Functions
constexpr std::string_view	ToString (HttpMethod method)
	Convert HttpMethod to string representation.

ICEBERG_REST_EXPORT Result< std::unique_ptr< FileIO > >	MakeCatalogFileIO (const RestCatalogProperties &config)
	Build the catalog FileIO: the configured `io-impl`, or the scheme-resolving FileIO by default.

ICEBERG_REST_EXPORT Result< std::unique_ptr< FileIO > >	MakeTableFileIO (const std::unordered_map< std::string, std::string > &catalog_config, const std::unordered_map< std::string, std::string > &table_config, const std::vector< StorageCredential > &storage_credentials)
	Build the configured table FileIO and apply storage credentials if present.

ICEBERG_REST_EXPORT std::string_view	TrimTrailingSlash (std::string_view str)
	Trim trailing slashes from a string.

ICEBERG_REST_EXPORT Result< std::string >	EncodeString (std::string_view str_to_encode)
	URL-encode a string (RFC 3986).

ICEBERG_REST_EXPORT Result< std::string >	DecodeString (std::string_view str_to_decode)
	URL-decode a string.

ICEBERG_REST_EXPORT Result< std::string >	EncodeNamespace (const Namespace &ns_to_encode, std::string_view separator="%1F")
	Encode a Namespace into a URL-safe component.

ICEBERG_REST_EXPORT Result< Namespace >	DecodeNamespace (std::string_view str_to_decode, std::string_view separator="%1F")
	Decode a URL-encoded namespace string back to a Namespace.

ICEBERG_REST_EXPORT std::unordered_map< std::string, std::string >	MergeConfigs (const std::unordered_map< std::string, std::string > &server_defaults, const std::unordered_map< std::string, std::string > &client_configs, const std::unordered_map< std::string, std::string > &server_overrides)
	Merge catalog configuration properties.

ICEBERG_REST_EXPORT std::string	GetStandardReasonPhrase (int32_t status_code)
	Get the standard HTTP reason phrase for a status code.

ICEBERG_REST_EXPORT std::string_view	ToString (PlanStatus status)

ICEBERG_REST_EXPORT Result< PlanStatus >	PlanStatusFromString (std::string_view status_str)

Variables
const std::string	kHeaderContentType = "Content-Type"

const std::string	kHeaderAccept = "Accept"

const std::string	kHeaderXClientVersion = "X-Client-Version"

const std::string	kHeaderUserAgent = "User-Agent"

const std::string	kMimeTypeApplicationJson = "application/json"

const std::string	kMimeTypeFormUrlEncoded = "application/x-www-form-urlencoded"

const std::string	kUserAgentPrefix = "iceberg-cpp/"

const std::string	kUserAgent = "iceberg-cpp/" ICEBERG_VERSION_STRING

const std::string	kQueryParamParent = "parent"

const std::string	kQueryParamPageToken = "page_token"

Detailed Description

REST catalog APIs.

Typedef Documentation

◆ HttpHeaders

using iceberg::rest::HttpHeaders = typedef std::map<std::string, std::string, CaseInsensitiveHeaderLess>

Single-value HTTP headers with case-insensitive names.

Repeated outgoing headers are intentionally not represented here. The SigV4 path signs headers through the AWS SDK request model, and the final transport uses cpr::Header; both are single-value, map-like containers that fold duplicate names. Keeping the REST request model single-value avoids exposing repeated-header behavior that cannot survive signing or transport.

Function Documentation

◆ DecodeNamespace()

ICEBERG_REST_EXPORT Result< Namespace > iceberg::rest::DecodeNamespace	(	std::string_view	str_to_decode,
		std::string_view	separator = `"%1F"`
	)

Decode a URL-encoded namespace string back to a Namespace.

Splits by the provided separator, then decodes each level separately using DecodeString.

Parameters

str_to_decode	The percent-encoded namespace string.
separator	The encoded separator used between namespace levels.

Returns: The decoded Namespace.

◆ DecodeString()

ICEBERG_REST_EXPORT Result< std::string > iceberg::rest::DecodeString ( std::string_view str_to_decode )

URL-decode a string.

Decodes percent-encoded characters (e.g., "%20" -> space). Uses libcurl's URL decoding via the CPR library.

Parameters

str_to_decode The encoded string to decode.

Returns: The decoded string or InvalidArgument if the string is invalid.

◆ EncodeNamespace()

ICEBERG_REST_EXPORT Result< std::string > iceberg::rest::EncodeNamespace	(	const Namespace &	ns_to_encode,
		std::string_view	separator = `"%1F"`
	)

Encode a Namespace into a URL-safe component.

Encodes each level separately using EncodeString, then joins them with the provided separator. The default matches the REST spec's historical "%1F".

Parameters

ns_to_encode	The namespace to encode.
separator	The encoded separator to place between namespace levels.

Returns: The percent-encoded namespace string suitable for URLs.

◆ EncodeString()

ICEBERG_REST_EXPORT Result< std::string > iceberg::rest::EncodeString ( std::string_view str_to_encode )

URL-encode a string (RFC 3986).

This implementation uses libcurl (via CPR), which follows RFC 3986 strictly:

Unreserved characters: [A-Z], [a-z], [0-9], "-", "_", ".", "~"
Space is encoded as "%20" (unlike Java's URLEncoder which uses "+").
All other characters are percent-encoded (XX).
Parameters

str_to_encode The string to encode.

Returns
The URL-encoded string or InvalidArgument if the string is invalid.

◆ GetStandardReasonPhrase()

ICEBERG_REST_EXPORT std::string iceberg::rest::GetStandardReasonPhrase ( int32_t status_code )

Get the standard HTTP reason phrase for a status code.

Returns the standard English reason phrase for common HTTP status codes. For unknown status codes, returns a generic "HTTP {code}" message.

Parameters

status_code The HTTP status code (e.g., 200, 404, 500).

Returns: The standard reason phrase string (e.g., "OK", "Not Found", "Internal Server Error").

◆ MergeConfigs()

ICEBERG_REST_EXPORT std::unordered_map< std::string, std::string > iceberg::rest::MergeConfigs	(	const std::unordered_map< std::string, std::string > &	server_defaults,
		const std::unordered_map< std::string, std::string > &	client_configs,
		const std::unordered_map< std::string, std::string > &	server_overrides
	)

Merge catalog configuration properties.

Merges three sets of configuration properties following the precedence order: server overrides > client configs > server defaults.

Parameters

server_defaults	Default properties provided by the server.
client_configs	Configuration properties from the client.
server_overrides	Override properties enforced by the server.

Returns: A merged map containing all properties with correct precedence.

◆ TrimTrailingSlash()

ICEBERG_REST_EXPORT std::string_view iceberg::rest::TrimTrailingSlash ( std::string_view str )

Trim trailing slashes from a string.

Parameters

str	A string to trim.

Returns: The trimmed string with all trailing slashes removed.

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ HttpHeaders

Function Documentation

◆ DecodeNamespace()

◆ DecodeString()

◆ EncodeNamespace()

◆ EncodeString()

◆ GetStandardReasonPhrase()

◆ MergeConfigs()

◆ TrimTrailingSlash()