Create a namespace

POST 
/v1/:prefix/namespaces

Create a namespace, with an optional set of properties. The server might also add properties, such as last_modified_time etc.

Request

Path Parameters

prefix stringrequired

The catalog name in Gravitino, as returned in defaults.prefix by GET /v1/config

Header Parameters

Idempotency-Key uuid
Possible values: >= 36 characters and <= 36 characters
Optional client-provided idempotency key for safe request retries.
When present, the server ensures no additional effects for requests that carry the same Idempotency-Key. If a prior request with this key has been finalized, the server returns an equivalent final response without re-running the operation. The response body may reflect a newer state of the catalog than existed at the time of the commit.
Finalization rules:
• Finalize & replay: 200, 201, 204, and deterministic terminal 4xx (including 409 such as AlreadyExists, NamespaceNotEmpty, etc.)
• Do not finalize (not stored/replayed): 5xx
Key Requirements:
• Key format: UUIDv7 in string form (RFC 9562).
• The idempotency key must be globally unique (no reuse across different operations).
• Catalogs SHOULD NOT expire keys before the end of the advertised token lifetime.
• If Idempotency-Key is used, clients MUST reuse the same key when retrying the same logical operation and MUST generate a new key for a different operation.

application/json

Body

required

namespace string[]required

Reference to one or more levels of a namespace

properties

object

Configured string to string map of properties for the namespace

property name* string

Responses

200

Represents a successful call to create a namespace. Returns the namespace created, as well as any properties that were stored for the namespace, including those the server might have added. Implementations are not required to support namespace properties.

application/json

Schema

Schema

namespace string[]required

Reference to one or more levels of a namespace

properties

object

Properties stored on the namespace, if supported by the server.

property name* string

Example (from schema)

{
  "namespace": [
    "accounting",
    "tax"
  ],
  "properties": {
    "owner": "Ralph",
    "created_at": "1452120468"
  }
}

Example

{
  "namespace": [
    "accounting",
    "tax"
  ],
  "properties": {
    "owner": "Ralph",
    "created_at": "1452120468"
  }
}

400

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure, such as invalid json. Usually serves application/json content, although in some cases simple text/plain content might be returned by the server's middleware.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}

401

Unauthorized. The REST Catalog SHOULD respond with the 401 UnauthorizedResponse when the access token provided is expired, revoked, malformed, or invalid for other reasons. The client MAY request a new access token and retry the request.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}

403

Forbidden. Authenticated user does not have the necessary permissions.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}

406

Not Acceptable / Unsupported Operation. The server does not support this operation.

application/json

Schema

Schema

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "message": "string",
  "type": "NoSuchNamespaceException",
  "code": 404,
  "stack": [
    "string"
  ]
}

Example

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

409

Conflict - The namespace already exists

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

NamespaceAlreadyExists

The requested namespace already exists

{
  "error": {
    "message": "The given namespace already exists",
    "type": "AlreadyExistsException",
    "code": 409
  }
}

419

This is an optional status response type that the REST Catalog can issue when the token has expired. The client MAY request a new access token and retry the request. 401 UnauthorizedResponse SHOULD be preferred over this response type on token expiry.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}

503

The service is not ready to handle the request, request could have been partially processed. The service may additionally send a Retry-After header to indicate when to retry, a non idempotent request should only be retried by the client when the Retry-After header is present.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}

5XX

A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Loading...