This is an automated email from the ASF dual-hosted git repository.
mchades pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new ea372a9565 [#14666] docs(open-api): Align fileset, topic and partition
contracts (#14667)
ea372a9565 is described below
commit ea372a9565bcf19d0b5fcd268d53b6da198cfa29
Author: mchades <[email protected]>
AuthorDate: Fri Nov 6 20:25:46 2026 +0800
[#14666] docs(open-api): Align fileset, topic and partition contracts
(#14667)
### What changes were proposed in this pull request?
- Document fileset default-location selection, including inherited
locations; add `removeComment`, missing-location errors and
disabled-filesystem behavior.
- Add shared 403/406 responses and operation-specific 501 responses with
JSON error examples.
- Clarify authorization-dependent 404 responses and partition purge
support; remove the inapplicable `alterTopic` already-exists 409
response.
### Why are the changes needed?
The OpenAPI definitions omit supported requests and error responses and
contain incorrect defaults.
Fixes #14666
### Does this PR introduce _any_ user-facing change?
Documentation/OpenAPI changes only. Server behavior is unchanged.
### How was this patch tested?
- `./gradlew :docs:spotlessApply :docs:build`.
- 42 existing tests passed: `TestVersioningFilter`,
`TestWebApplicationExceptionMapper`, and selected
`TestFilesetCatalogOperations` cases.
- Validated 16 operations, 72 error-example references, two create
examples and the `removeComment` schema.
- `git diff --check`.
Full server, Kafka and Hive integration tests were not run.
---
docs/open-api/filesets.yaml | 171 ++++++++++++++++++++++++++++++++++++------
docs/open-api/openapi.yaml | 37 +++++++++
docs/open-api/partitions.yaml | 69 +++++++++++++++--
docs/open-api/topics.yaml | 72 +++++++++++++-----
4 files changed, 299 insertions(+), 50 deletions(-)
diff --git a/docs/open-api/filesets.yaml b/docs/open-api/filesets.yaml
index 673e1047f0..c41238e88f 100644
--- a/docs/open-api/filesets.yaml
+++ b/docs/open-api/filesets.yaml
@@ -35,7 +35,11 @@ paths:
$ref: "./openapi.yaml#/components/responses/EntityListResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
- "5xx":
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
post:
@@ -51,9 +55,17 @@ paths:
examples:
FilesetCreateRequest:
$ref: "#/components/examples/FilesetCreateRequest"
+ MultipleLocationsFilesetCreateRequest:
+ $ref:
"#/components/examples/MultipleLocationsFilesetCreateRequest"
responses:
"200":
$ref: "#/components/responses/FilesetResponse"
+ "400":
+ $ref: "#/components/responses/FilesetCreateBadRequestResponse"
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
"409":
description: Conflict - The target fileset already exists
content:
@@ -63,7 +75,7 @@ paths:
examples:
FilesetAlreadyExistsErrorResponse:
$ref: "#/components/examples/FilesetAlreadyExistsException"
- "5xx":
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
@@ -83,10 +95,14 @@ paths:
responses:
"200":
$ref: "#/components/responses/FilesetResponse"
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
"404":
- description: Not Found - The target fileset does not exist
+ description: >-
+ Not Found - The fileset or its parent resource does not exist.
When authorization
+ is enabled, a missing metalake returns 403 instead.
content:
- application/vnd.gravitino.v1+json:
+ application/json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
@@ -98,7 +114,9 @@ paths:
$ref:
"./schemas.yaml#/components/examples/NoSuchSchemaException"
NoSuchFilesetException:
$ref: "#/components/examples/NoSuchFilesetException"
- "5xx":
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
put:
@@ -117,10 +135,14 @@ paths:
$ref: "#/components/responses/FilesetResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
"404":
- description: Not Found - The target fileset does not exist
+ description: >-
+ Not Found - The fileset or its parent resource does not exist.
When authorization
+ is enabled, a missing metalake returns 403 instead.
content:
- application/vnd.gravitino.v1+json:
+ application/json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
@@ -132,6 +154,8 @@ paths:
$ref:
"./schemas.yaml#/components/examples/NoSuchSchemaException"
NoSuchFilesetException:
$ref: "#/components/examples/NoSuchFilesetException"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
"409":
description: Conflict - The target fileset already exists
content:
@@ -141,7 +165,7 @@ paths:
examples:
FilesetAlreadyExistsErrorResponse:
$ref: "#/components/examples/FilesetAlreadyExistsException"
- "5xx":
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
delete:
@@ -154,7 +178,11 @@ paths:
$ref: "./openapi.yaml#/components/responses/DropResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
- "5xx":
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/filesets/{fileset}/location:
@@ -169,7 +197,10 @@ paths:
- location
summary: Get file location
operationId: getFileLocation
- description: Returns the specified file location object
+ description: >-
+ Returns the specified file location object by resolving the storage
location and
+ sub path. This operation remains available when the catalog property
+ disable-filesystem-ops is true because it does not access the
filesystem.
parameters:
- name: sub_path
in: query
@@ -187,17 +218,23 @@ paths:
required: false
schema:
type: string
- default: "default"
- description: The location name in the fileset
+ description: >-
+ The location name in the fileset. When omitted, the server uses
the only storage
+ location, or properties.default-location-name if there are
multiple locations.
+ An unknown name returns HTTP 404 with NoSuchLocationNameException.
responses:
"200":
$ref: "#/components/responses/FileLocationResponse"
"400":
$ref: "#/components/responses/InvalidSubPathErrorResponse"
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
"404":
- description: Not Found - The target fileset does not exist
+ description: >-
+ Not Found - The fileset, its parent resource, or the specified
location name
+ does not exist. When authorization is enabled, a missing metalake
returns 403 instead.
content:
- application/vnd.gravitino.v1+json:
+ application/json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
@@ -209,7 +246,11 @@ paths:
$ref:
"./schemas.yaml#/components/examples/NoSuchSchemaException"
NoSuchFilesetException:
$ref: "#/components/examples/NoSuchFilesetException"
- "5xx":
+ NoSuchLocationNameException:
+ $ref: "#/components/examples/NoSuchLocationNameException"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/filesets/{fileset}/files:
@@ -224,7 +265,10 @@ paths:
- fileset
summary: List files
operationId: listFilesetFiles
- description: List metadata of files and directories in a fileset
+ description: >-
+ Lists metadata of files and directories in a fileset. Returns HTTP 501
when the
+ catalog property disable-filesystem-ops is true. The getFileLocation
operation
+ remains available in that configuration.
parameters:
- name: sub_path
in: query
@@ -244,16 +288,23 @@ paths:
required: false
schema:
type: string
- description: The name of the storage location
+ description: >-
+ The location name in the fileset. When omitted, the server uses
the only storage
+ location, or properties.default-location-name if there are
multiple locations.
+ An unknown name returns HTTP 404 with NoSuchLocationNameException.
responses:
"200":
$ref: "#/components/responses/FileInfoListResponse"
"400":
$ref: "#/components/responses/InvalidSubPathErrorResponse"
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
"404":
- description: Not Found – the target fileset or locationName does not
exist
+ description: >-
+ Not Found - The fileset, its parent resource, or the specified
location name
+ does not exist. When authorization is enabled, a missing metalake
returns 403 instead.
content:
- application/vnd.gravitino.v1+json:
+ application/json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
@@ -265,7 +316,13 @@ paths:
$ref:
"./schemas.yaml#/components/examples/NoSuchSchemaException"
NoSuchFilesetException:
$ref: "#/components/examples/NoSuchFilesetException"
- "5xx":
+ NoSuchLocationNameException:
+ $ref: "#/components/examples/NoSuchLocationNameException"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "501":
+ $ref:
"#/components/responses/FilesystemOperationsDisabledErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
components:
@@ -343,22 +400,41 @@ components:
nullable: true
storageLocation:
type: string
- description: The location of the fileset. If the storage location of
managed fileset is empty, it will \
- use the location of namespace. The storage location of external
fileset must be set.
+ description: >-
+ The location of the fileset. When omitted for a managed fileset,
the location is
+ derived from its schema, which may inherit locations from the
catalog. External
+ filesets must specify a storage location.
nullable: true
storageLocations:
type: object
- description: The storage locations of the fileset. If the storage
location of managed fileset is empty, \
- it will use the location of namespace. The storage locations of
external fileset must be set.
+ description: >-
+ The named storage locations of the fileset. Locations are resolved
by name:
+ request locations override schema locations, which override
catalog locations
+ with the same name. Other inherited location names are retained.
Managed filesets
+ may omit storageLocations and use locations derived from their
schema and catalog.
+ External filesets must specify storage locations. When the
resulting fileset has
+ more than one location, including inherited locations, properties
must include
+ default-location-name with a value matching one of the resolved
location keys.
nullable: true
default: { }
additionalProperties:
type: string
properties:
type: object
- description: The properties of the fileset. Can be empty.
+ description: >-
+ The properties of the fileset. When the resulting fileset has
multiple storage locations,
+ default-location-name is required and must match one of the
resolved location keys;
+ otherwise creation returns HTTP 400. Managed filesets may inherit
locations from the
+ schema or catalog even when storageLocations is omitted.
nullable: true
default: {}
+ properties:
+ default-location-name:
+ type: string
+ description: >-
+ The default storage location key. Required when there is more
than one resolved
+ storage location. For a single location, the server fills in
that location's key when
+ this property is omitted; an explicit value must match that
key.
additionalProperties:
type: string
secretBindings:
@@ -393,6 +469,7 @@ components:
- $ref: "#/components/schemas/RenameFilesetRequest"
- $ref: "#/components/schemas/SetFilesetPropertyRequest"
- $ref: "#/components/schemas/UpdateFilesetCommentRequest"
+ - $ref: "#/components/schemas/RemoveFilesetCommentRequest"
- $ref: "#/components/schemas/UpdateFilesetTypeRequest"
- $ref: "#/components/schemas/RemoveFilesetPropertyRequest"
- $ref: "#/components/schemas/SetFilesetSecretBindingRequest"
@@ -403,6 +480,7 @@ components:
rename: "#/components/schemas/RenameFilesetRequest"
setProperty: "#/components/schemas/SetFilesetPropertyRequest"
updateComment: "#/components/schemas/UpdateFilesetCommentRequest"
+ removeComment: "#/components/schemas/RemoveFilesetCommentRequest"
updateType: "#/components/schemas/UpdateFilesetTypeRequest"
removeProperty: "#/components/schemas/RemoveFilesetPropertyRequest"
setSecretBinding:
"#/components/schemas/SetFilesetSecretBindingRequest"
@@ -593,6 +671,32 @@ components:
}
responses:
+ FilesetCreateBadRequestResponse:
+ description: >-
+ Bad Request - The fileset creation request is invalid. For multiple
storage
+ locations, properties.default-location-name must name one of the
location keys.
+ content:
+ application/json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ example:
+ code: 1001
+ type: IllegalArgumentException
+ message: >-
+ The fileset property default-location-name must be set and must
be one of
+ the fileset locations, location names: [primary, secondary],
default location name: null
+
+ FilesystemOperationsDisabledErrorResponse:
+ description: Not Implemented - Filesystem operations are disabled by the
catalog property disable-filesystem-ops
+ content:
+ application/json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ example:
+ code: 1006
+ type: UnsupportedOperationException
+ message: Filesystem operations are disabled on this server
+
InvalidSubPathErrorResponse:
description: >-
The sub path does not satisfy the fileset path requirements.
@@ -677,6 +781,17 @@ components:
}
}
+ MultipleLocationsFilesetCreateRequest:
+ value:
+ name: fileset1
+ type: EXTERNAL
+ comment: A fileset with two storage locations
+ storageLocations:
+ primary: s3://bucket/path
+ secondary: s3://other-bucket/path
+ properties:
+ default-location-name: primary
+
FilesetResponse:
value: {
"code": 0,
@@ -738,3 +853,9 @@ components:
"java.lang.NoSuchFilesetException: Fileset does not exist"
]
}
+
+ NoSuchLocationNameException:
+ value:
+ code: 1003
+ type: NoSuchLocationNameException
+ message: Location name missing does not exist in fileset fileset1
diff --git a/docs/open-api/openapi.yaml b/docs/open-api/openapi.yaml
index 67bd9ee69d..9e4d335f33 100644
--- a/docs/open-api/openapi.yaml
+++ b/docs/open-api/openapi.yaml
@@ -422,6 +422,43 @@ components:
"message": "Malformed request"
}
+ ForbiddenErrorResponse:
+ description: >-
+ Forbidden - The caller is not allowed to perform the operation. When
authorization
+ is enabled, a missing metalake or a caller who is not a member of the
metalake
+ also returns 403.
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorModel"
+ example:
+ code: 1008
+ type: ForbiddenException
+ message: Current user alice is not a member of metalake metalake1,
or the metalake does not exist
+
+ NotAcceptableErrorResponse:
+ description: >-
+ Not Acceptable - The requested API version is unsupported, or the
effective
+ Accept header cannot be served by this operation. When Accept has no
Gravitino
+ API version, including application/json, */*, or an absent header, the
server
+ uses the version from Content-Type if present, otherwise the default
API version.
+ Both cases return HTTP 406 with a JSON ErrorModel response.
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/ErrorModel"
+ examples:
+ UnsupportedApiVersion:
+ value:
+ code: 1001
+ type: IllegalArgumentException
+ message: Unsupported version v99 in request header
+ IncompatibleAccept:
+ value:
+ code: 1000
+ type: RESTException
+ message: HTTP 406 Not Acceptable
+
ServerErrorResponse:
description:
A server-side problem that might not be addressable from the client
diff --git a/docs/open-api/partitions.yaml b/docs/open-api/partitions.yaml
index 45fdd54dd0..1f9072652b 100644
--- a/docs/open-api/partitions.yaml
+++ b/docs/open-api/partitions.yaml
@@ -49,7 +49,13 @@ paths:
$ref: "#/components/examples/PartitionListResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
- "5xx":
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "501":
+ $ref:
"#/components/responses/PartitionUnsupportedOperationErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
post:
@@ -68,6 +74,10 @@ paths:
responses:
"200":
$ref: "#/components/responses/PartitionListResponse"
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
"409":
description: Conflict - The target partition already exists
content:
@@ -77,7 +87,9 @@ paths:
examples:
PartitionAlreadyExistsErrorResponse:
$ref:
"#/components/examples/PartitionAlreadyExistsErrorResponse"
- "5xx":
+ "501":
+ $ref:
"#/components/responses/PartitionUnsupportedOperationErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/tables/{table}/partitions/{partition}:
@@ -97,10 +109,14 @@ paths:
responses:
"200":
$ref: "#/components/responses/PartitionResponse"
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
"404":
- description: Not Found - The specified partition does not exist
+ description: >-
+ Not Found - The partition or its parent resource does not exist.
When authorization
+ is enabled, a missing metalake returns 403 instead.
content:
- application/vnd.gravitino.v1+json:
+ application/json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
@@ -114,7 +130,11 @@ paths:
$ref:
"./tables.yaml#/components/examples/NoSuchTableException"
NoSuchPartitionException:
$ref: "#/components/examples/NoSuchPartitionException"
- "5xx":
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "501":
+ $ref:
"#/components/responses/PartitionUnsupportedOperationErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
delete:
@@ -130,7 +150,13 @@ paths:
$ref: "./openapi.yaml#/components/responses/DropResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
- "5xx":
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "501":
+ $ref:
"#/components/responses/PartitionUnsupportedOperationErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
@@ -148,7 +174,9 @@ components:
purge:
name: purge
in: query
- description: Purge the partition data
+ description: >-
+ Purge the partition data. Support depends on the catalog provider.
Setting this
+ parameter to true returns HTTP 501 if the provider does not support
partition purging.
required: false
schema:
type: boolean
@@ -347,6 +375,33 @@ components:
$ref: "#/components/schemas/Properties"
responses:
+ PartitionUnsupportedOperationErrorResponse:
+ description: >-
+ Not Implemented - The table does not support partition operations or
the requested
+ partition operation is unsupported. For DELETE with purge=true, this
also includes
+ tables that do not support partition purging.
+ content:
+ application/json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ PartitionOperationsUnsupported:
+ summary: The table does not support partition operations
+ value:
+ code: 1006
+ type: UnsupportedOperationException
+ message: >-
+ Failed to operate partition(s) operation [LIST] of table
[table1], reason
+ [Table does not support partition operations.]
+ PartitionPurgeUnsupported:
+ summary: Partition purging is unsupported for DELETE with
purge=true
+ value:
+ code: 1006
+ type: UnsupportedOperationException
+ message: >-
+ Failed to operate partition(s) operation [DROP] of table
[table1], reason
+ [Partition purging is not supported]
+
PartitionListResponse:
description: Returns list of partition objects
diff --git a/docs/open-api/topics.yaml b/docs/open-api/topics.yaml
index 3b721d9bef..c2af306db5 100644
--- a/docs/open-api/topics.yaml
+++ b/docs/open-api/topics.yaml
@@ -35,7 +35,13 @@ paths:
$ref: "./openapi.yaml#/components/responses/EntityListResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
- "5xx":
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "501":
+ $ref: "#/components/responses/TopicUnsupportedOperationErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
post:
@@ -56,6 +62,10 @@ paths:
$ref: "#/components/responses/TopicResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
"409":
description: Conflict - The target topic already exists
content:
@@ -65,7 +75,9 @@ paths:
examples:
TopicAlreadyExistsErrorResponse:
$ref: "#/components/examples/TopicAlreadyExistsException"
- "5xx":
+ "501":
+ $ref: "#/components/responses/TopicUnsupportedOperationErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/topics/{topic}:
@@ -84,10 +96,14 @@ paths:
responses:
"200":
$ref: "#/components/responses/TopicResponse"
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
"404":
- description: Not Found - The target topic does not exist
+ description: >-
+ Not Found - The topic or its parent resource does not exist. When
authorization
+ is enabled, a missing metalake returns 403 instead.
content:
- application/vnd.gravitino.v1+json:
+ application/json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
@@ -99,7 +115,11 @@ paths:
$ref:
"./schemas.yaml#/components/examples/NoSuchSchemaException"
NoSuchTopicException:
$ref: "#/components/examples/NoSuchTopicException"
- "5xx":
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "501":
+ $ref: "#/components/responses/TopicUnsupportedOperationErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
put:
@@ -118,10 +138,14 @@ paths:
$ref: "#/components/responses/TopicResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
"404":
- description: Not Found - The target topic does not exist
+ description: >-
+ Not Found - The topic or its parent resource does not exist. When
authorization
+ is enabled, a missing metalake returns 403 instead.
content:
- application/vnd.gravitino.v1+json:
+ application/json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
@@ -133,16 +157,11 @@ paths:
$ref:
"./schemas.yaml#/components/examples/NoSuchSchemaException"
NoSuchTopicException:
$ref: "#/components/examples/NoSuchTopicException"
- "409":
- description: Conflict - The target topic already exists
- content:
- application/vnd.gravitino.v1+json:
- schema:
- $ref: "./openapi.yaml#/components/schemas/ErrorModel"
- examples:
- TopicAlreadyExistsErrorResponse:
- $ref: "#/components/examples/TopicAlreadyExistsException"
- "5xx":
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "501":
+ $ref: "#/components/responses/TopicUnsupportedOperationErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
delete:
@@ -155,7 +174,13 @@ paths:
$ref: "./openapi.yaml#/components/responses/DropResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
- "5xx":
+ "403":
+ $ref: "./openapi.yaml#/components/responses/ForbiddenErrorResponse"
+ "406":
+ $ref:
"./openapi.yaml#/components/responses/NotAcceptableErrorResponse"
+ "501":
+ $ref: "#/components/responses/TopicUnsupportedOperationErrorResponse"
+ "5XX":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
components:
@@ -282,6 +307,17 @@ components:
}
responses:
+ TopicUnsupportedOperationErrorResponse:
+ description: Not Implemented - The catalog does not support topic
operations or the requested topic operation
+ content:
+ application/json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ example:
+ code: 1006
+ type: UnsupportedOperationException
+ message: Catalog does not support topic operations
+
TopicResponse:
description: Returns include the topic object
content:
