You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@iceberg.apache.org by GitBox <gi...@apache.org> on 2021/12/18 00:27:51 UTC
[GitHub] [iceberg] kbendick opened a new pull request #3770: [Rest Catalog] Initial OpenAPI Spec for a Rest Catalog
kbendick opened a new pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770
This is a follow up to the original PR, https://github.com/apache/iceberg/pull/3561, as the discussion there got too large.
We mostly handle namespace related concerns here. Table related objects will come in a follow up PR.
I have followed up on comments and suggestions that were brought up on the other PR, as well as some conclusions that we've come to in the meeting.
The easiest way to view this document is by importing the YAML directly into editor.swagger.io
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771759923
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
Review comment:
Maybe specify that the namespace does not exist?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r773513125
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
Review comment:
@rymurr and @jackye1995, what do you think about adding a body to the HEAD responses? I think it would be nice to do for consistency.
As an alternative, maybe we should avoid HEAD routes so that we don't have to deviate? We might not actually need this since the GET route isn't expensive. It just returns the namespace metadata.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r773513680
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
Review comment:
I'm wondering if we actually want this. It makes sense to have a HEAD route for tables since loading them can be expensive (sending the full metadata JSON). But here you may as well run the GET route because it's simple to look up the database params.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777763678
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
Review comment:
I'd say we keep it for now but consider dropping it. Possibly we can mark it as optional somehow in a follow up?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777768107
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
Review comment:
Added 400 everywhere.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771772054
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
Review comment:
I found a nice middle ground and will be updating to that over the next 24-48 hours. =)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771762857
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
Review comment:
The difference would be 8 additional lines per every single response code (202, 404, 406, 422) vs zero or one additional line.
But the content way is probably more standard (but will make the document a lot larger).
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
Review comment:
Done.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771758854
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,696 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found - Parent namespace does not exist
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - properties
+ - defaults
+ properties:
+ overrrides:
+ type: object
+ nullable: false
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ nullable: false
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ nullable: false
+ name:
+ type: string
+ nullable: false
+
+ UpdatePropertiesRequest:
+ type: object
+ properties:
+ removables:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ IcebergResponseObject:
+ description: JSON wrapper for all response bodies, with a data object and / or an error object
+ content:
+ application/json:
+ schema:
+ anyOf:
+ - $ref: '#/components/schemas/ResponseDataObject'
+ - $ref: '#/components/schemas/ResponseErrorObject'
+ example: { "data": { ... }, "error": { } }
Review comment:
Yeah that's a good idea.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771760019
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
Review comment:
Not all error codes in this doc use quotes. Is there a distinction between when you'd use quotes or not?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771764660
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ name:
+ type: string
+ nullable: false
+
+ UpdatePropertiesRequest:
+ type: object
+ properties:
+ removables:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ 404Response:
+ description: Generic example response to demonstrate a 404's general form.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example: {
+ "error": {
+ "message": "The given namespace does not exist",
+ "type": "NoSuchNamespaceException",
+ "code": 404
+ }
+ }
+
+ IcebergResponseObject:
+ description: JSON wrapper for all response bodies, with a data object and / or an error object
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ data:
+ $ref: '#/components/schemas/ResponseDataObject'
+ error:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example: { "data": { ... }, "error": { } }
+
+ DropTableResponse:
+ description: A successful call to drop a table
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ dropped:
+ type: boolean
+ description: true if the table was found and removed from the catalog
+ purged:
+ type: boolean
+ description: whether the underlying data was purged or is being purged
+
+ GetNamespaceResponse:
+ description: Returns a namespace and the properties stored on it
Review comment:
How I have it currently, on the response, it's defaulted to `{ }`. As within the Iceberg code, we don't really have the concept of a Namespace without properties. It's just implicit in some places that it's not supported.
I'll throw the words optional or when supported on there though to be more precise.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771766804
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
Review comment:
Updated to an explicit `DropNamespaceResponse`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771758537
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
Review comment:
If this is generic, then we should just say it is an optional parent namespace, without necessarily stating what its purpose is ("under which to list namespaces").
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r772872674
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
Review comment:
So TIL it seems that originally there was just `schemas`. So it has some of the most support for JSON schema and things (like pattern checks that can be added as javax annotations etc).
Other things are newer and less feature rich. I've seen several tutorials with basic error classes, and they've mostly done it via `schemas`. I'm not sure if that's just to lessen the overhead for the article, but since we're getting rid of the `data` wrapper, I'm going to keep the `error` wrapper in schemas for now.
Keeping the `ResponseErrorObject` in schemas allows it to have much more control over what is and is not excepted, what's required to be defined, etc.
I'm open to moving it, but for now it seems like just getting rid of the `data` wrapper and the top level wrapper and keeping `ResponseErrorObject` would be good.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r773506911
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
Review comment:
Yeah. At present we've left it out for simplicity (as there's already been a lot of discussion around just this), so it will be include it in a follow up PR, but there can be a callback URL that a client can subscribe to:
https://swagger.io/docs/specification/callbacks/
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1007769255
I merged this and we can pick up changes from @rymurr's review as we extend this. Thanks @jackye1995 and everyone on the original PR for all the input, and especially to @kbendick for getting this ready!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue merged pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue merged pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick removed a comment on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick removed a comment on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-997120898
> Overall, this looks good to me. I think that one of the main things to do is add consistency since there are a lot of differences that make it hard to consume as the yaml spec. I think that part of the motivation is to not have a huge number of schemas and response types so this is embedding them in some of the routes. But that ends up being a little confusing overall.
Yeah. With the OpenAPI doc, there really is either a choice between a long form document (where everything is spelled out), or a shorter form document that is harder to read if you're not used to looking at OpenAPI docs.
I'll make it more consistent, but I will warn you that the document size will likely double.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771758799
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,696 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found - Parent namespace does not exist
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - properties
Review comment:
Oh good catch. Fixing.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771762235
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
Review comment:
Let me know if you prefer the `content` metadata or this shorthand.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771765603
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ name:
+ type: string
+ nullable: false
+
+ UpdatePropertiesRequest:
+ type: object
+ properties:
+ removables:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ 404Response:
+ description: Generic example response to demonstrate a 404's general form.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example: {
+ "error": {
+ "message": "The given namespace does not exist",
+ "type": "NoSuchNamespaceException",
+ "code": 404
+ }
+ }
+
+ IcebergResponseObject:
+ description: JSON wrapper for all response bodies, with a data object and / or an error object
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ data:
+ $ref: '#/components/schemas/ResponseDataObject'
+ error:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example: { "data": { ... }, "error": { } }
+
+ DropTableResponse:
+ description: A successful call to drop a table
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ dropped:
+ type: boolean
+ description: true if the table was found and removed from the catalog
+ purged:
+ type: boolean
+ description: whether the underlying data was purged or is being purged
+
+ GetNamespaceResponse:
+ description: Returns a namespace and the properties stored on it
Review comment:
Updated. I also indicated that `namespaces` is a required field, as well as gave a default value of an empty object to `properties` and marked is as the equivalent of `@Nullable`.
When the `properties` field is null, it indicates the server doesn't support namespace properties. If it returns an empty object, then there are simply no properties presently stored on this namesapce.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771765944
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
Review comment:
Yeah. I hesitated to add this in (especially as I've been working on adding cascade support), but it is on the interface definition (as indicated by the `@throws` section of the javadoc): https://github.com/apache/iceberg/blob/c5d3d1ca19105d7f525f9912bd7f7f2e4507541b/api/src/main/java/org/apache/iceberg/catalog/SupportsNamespaces.java#L98-L105
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] szehon-ho commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
szehon-ho commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r773496543
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
Review comment:
Just curious, any way to check if async action finished?
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
Review comment:
Spelling
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
Review comment:
Will we also have an error code like 500 for an unexpected exception on server side?
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not rturn a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
Review comment:
Below we have NoSuchTable and NoSuchNamespace, curious, should we follow it? (Sorry I guess it was already commented but I didn't follow the resolution)
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not rturn a response body.
Review comment:
Spelling
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rymurr commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rymurr commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1005012173
Hey all, I just got back today. Will review this asap tomorrow morning. Hope I am not holding anyone up?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777305107
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
Review comment:
I see here, in the Confluent Kafka REST open api doc, that they have a `5xx` response. This makes sense to me given that 5xx is often thrown by the server and usually is used that way: https://github.com/confluentinc/kafka-rest/blob/master/api/v3/openapi.yaml#L77-L78
We can iterate on that if we need specific 5xx errors, but I think that's sufficient for now.
As a side note, I am likely going to reorganize some of this document in the style they use, but in a follow up PR. We can discuss then which parts we would like to organize around and which we wouldn't. For now though, I'd like to keep it as close to what we agreed on just to be able to move forward. There will be more PRs opened against this for sure 👍
But I've added 5xx. Will be adding 400 as well. Thank you both for the review!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777609358
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
Review comment:
I think this is closer to a conflict than a bad request. The request isn't malformed, it conflicts with the current state of the catalog. Another request may have created the namespace concurrently and this is what I'd expect in that case.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rymurr commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rymurr commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1007265607
Please don't wait for me. I will get to it next week and we can do a follow
up if I raise anything.
On Thu, Jan 6, 2022 at 6:21 AM Kyle Bendickson ***@***.***>
wrote:
> @rymurr <https://github.com/rymurr>, any comments? We'd like to start
> working on the follow ups if you have a chance to take a look.
>
> cc @nastra <https://github.com/nastra> as well @rymurr
> <https://github.com/rymurr> in case you have any final comments on the
> doc as it is. I know it's a lot to ingest, but I think if we can get this
> initial doc in, then we can hopefully make things smaller and begin to
> follow a more consistent pattern that we'll adapt to as we all work more
> with OpenAPI.
>
> Please keep in mind this is just the first of many patches and things to
> get this off the ground, so that work can begin somewhat more parallelized.
> Also, once we're all working on this API, if things need to be changed for
> practical reasons etc, I'm not opposed to that. I think those things will
> become more apparent as we make more progress. 😄
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/apache/iceberg/pull/3770#issuecomment-1006293595>, or
> unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AAPNXIL4GEPQKYMPM3KLX53UUURGTANCNFSM5KJ7LIWA>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777764473
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
Review comment:
I have updated to be consistent with empty lines between verbs, including an empty line after the path and parameters and the first verb.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777763876
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
Review comment:
I pulled this directly from the documentation, but I can use a more realistic example like I did elsewhere (`accounting.tax` is what I tended to use elsewhere).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771764253
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
Review comment:
This isn't a generic parameter. There's only one usage of it, and it's rather specific. So I've moved it to the one place it is used. If we wind up using it more than once (and thus introducing duplication), I'll move it back down here and then make it generic. But for the moment I think it's better as not a generic parameter. Feel free to suggest a generic description to use if you feel otherwise.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
Review comment:
Updated.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771761530
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
Review comment:
Actually, since it has the description of the behavior of what would happen if it's not included, I think it should go under the parameters section of the single route that uses it. Let me think about it and see if there's a good place to document that behavior and leave this generic down here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771758674
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
Review comment:
This looks like documentation for a use, not for the generic parameter.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771758586
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
Review comment:
Also remove `%00` here for clarity.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771760357
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
Review comment:
Is the schema of the `dropped` payload documented anywhere? If not, we should add it.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771772318
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ name:
+ type: string
+ nullable: false
+
+ UpdatePropertiesRequest:
+ type: object
+ properties:
+ removables:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ 404Response:
+ description: Generic example response to demonstrate a 404's general form.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example: {
+ "error": {
+ "message": "The given namespace does not exist",
+ "type": "NoSuchNamespaceException",
+ "code": 404
+ }
+ }
+
+ IcebergResponseObject:
+ description: JSON wrapper for all response bodies, with a data object and / or an error object
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ data:
+ $ref: '#/components/schemas/ResponseDataObject'
+ error:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example: { "data": { ... }, "error": { } }
+
+ DropTableResponse:
+ description: A successful call to drop a table
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ dropped:
+ type: boolean
+ description: true if the table was found and removed from the catalog
+ purged:
+ type: boolean
+ description: whether the underlying data was purged or is being purged
+
+ GetNamespaceResponse:
+ description: Returns a namespace and the properties stored on it
Review comment:
We don't have to keep that way of distinguishing `null` vs `{}`, especially as there's no way to describe it in the OpenAPI document that I'm aware of, but it seemed like the easiest way to indicate truly empty vs not supported (and thus empty).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771772080
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
Review comment:
We spoke offline and we're keeping it in the examples to show. I might add a note bout the URL encoding later, once I find the right words for it.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1006124021
@rymurr, any comments? We'd like to start working on the follow ups if you have a chance to take a look.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1005040212
Should be fine. Thanks for taking a look, @rymurr!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777767979
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
Review comment:
Updated to `source` and `destination`. I have a few things I'm going to drop since they can be inferred.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
Review comment:
Updated to `source` and `destination`. I have a few things I'm going to drop since they can be inferred.
Oh and I added an example.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1004309804
Thanks for the pending thoughts @jackye1995! I'll respond a bit, and then we'll keep these for later discussion as well (assuming there will be more discussion groups / follow up PRs etc)
> 1. if it's better to have specific operation routes for non-RESTful operations
Agreed.
> 2. head table/namespace operation with response, if we do that what set of fields should be in the response
So currently, there's no set of fields in the response for HEAD requests. That's what the response code and just the string `description` represents. Technically, HEAD requests are not supposed to have a response body. However, so many famous APIs do that I think we can add them in a follow up.
> 3. if pagination of response is needed when there are too many metadata log or snapshots
I had brought up pagination for one or two routes, but it was deemed as somewhat premature. I think eventually we will definitely need some kind of pagination for sure.
> 4. progress tracking for table purge
Will be coming in a follow up.
> 5. drop namespace cascade
That one is not currently implemented, but I agree. Once we finish implementing it, it should be easy to add in. We can start considering where to put it in the API here sooner. Probably as a query parameter I would think.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777610057
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
Review comment:
+1 for consistency. I like the empty line between verbs.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777609803
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
Review comment:
Yeah, if a service ever needs to send 400, then I think it is best to add it to this API doc.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777620373
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ name:
+ type: string
+ nullable: false
+
+ UpdateNamespacePropertiesRequest:
+ type: object
+ properties:
+ removals:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ # Note that this is a representative example response for use as a shorthand in the spec.
+ # The fields `message` and `type` as indicated here are not presently prescriptive.
+ UnauthorizedResponse:
+ description: Unauthorized. The client does not have permissions to call this route.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example: {
+ "error": {
+ "message": "Not authorized to make this request",
+ "type": "NotAuthorizedException",
+ "code": 401
+ }
+ }
+
+ # Note that this is a representative example response for use as a shorthand in the spec.
+ # The fields `message` and `type` as indicated here are not presently prescriptive.
+ UnsupportedOperationResponse:
+ description: Not Acceptable / Unsuported Operation. The server does not support this operation.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example: {
+ "error": {
+ "message": "The server does not support this operation",
+ "type": "UnsupportedOperationException",
+ "code": 406
+ }
+ }
+
+ IcebergErrorResponse:
+ description: JSON wrapper for all error responses (non-2xx)
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ error:
+ $ref: '#/components/schemas/StandardErrorWrapper'
+ additionalProperties: false
+ example: {
+ "error": {
+ "message": "The server does not support this operation",
+ "type": "UnsupportedOperationException",
+ "code": 406
+ } }
+
+ DropTableResponse:
+ description: A successful call to drop a table
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ dropped:
+ type: boolean
+ description: true if the table was found and removed from the catalog
+ purged:
+ type: boolean
+ description: whether the underlying data was purged or is being purged
+
+ DropNamespaceResponse:
+ description: A successful call to drop a namespace
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ dropped:
+ description: true if the namespace was dropped
+ type: boolean
+
+ GetNamespaceResponse:
+ description:
+ Returns a namespace, as well as any properties stored on the namespace if namespace properties
+ are supported by the server.
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description:
+ Properties stored on the namespace, if supported by the server.
+ If the server does not support namespace properties, it should return null for this field.
+ If namespace properties are supported, but none are set, it should return an empty object.
+ example: { "owner": "Ralph", 'transient_lastDdlTime': '1452120468' }
+ default: { }
+ nullable: true
+
+ ListTablesResponse:
+ description: A list of table identifiers
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ uniqueItems: true
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ ListNamespacesResponse:
+ description: A list of namespaces
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ uniqueItems: true
+ items:
+ $ref: '#/components/schemas/Namespace'
+
+ UpdateNamespacePropertiesResponse:
+ description: JSON data response for a synchronous update properties request.
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - updated
Review comment:
I think this comment applies here as well: https://github.com/apache/iceberg/pull/3770/files#r777620121
I'd probably leave these as required, but it is minor to me.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777612873
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
Review comment:
Wouldn't it be better to use a `GET` request to `/v1/namespaces/{namespace}/tables/{table}/exists` instead?
But I don't think that's worth it. Let's just leave this as-is.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771759519
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - properties
+ - defaults
+ properties:
+ overrrides:
+ type: object
+ nullable: false
Review comment:
Removed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-999175673
I'm +1 for committing this. I think it's a great start on the REST catalog spec and that the namespace basics are ready to go.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777764473
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
Review comment:
I have updated to be consistent with empty lines between verbs.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1004455929
@jackye1995, it looks like we're mostly in agreement now:
> 1. if it's better to have specific operation routes for non-RESTful operations
> 2. head table/namespace operation with response, if we do that what set of fields should be in the response
> 3. if pagination of response is needed when there are too many metadata log or snapshots
> 4. progress tracking for table purge
> 5. drop namespace cascade
For 1, I think we're just trying to decide on the path for the `/tables/rename` route, right? I like the simplicity of `tables` and I don't think it will be confusing to have operation routes there. That's where I'd add multi-table transactions as well, which don't cleanly fit into a single REST resource.
For 2, I think we should remove the HEAD request for namespaces and leave the tables HEAD request without response bodies. We're probably agreed?
These should be added in follow-ups. 3, 4, and 5 are not strictly required so I like the idea of adding them in follow-ups in parallel
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777778208
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
Review comment:
Updated.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1004471026
There's a failing Hive test that by definition can't be related to this PR (as this PR only adds an initial YAML document).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1006293595
> @rymurr, any comments? We'd like to start working on the follow ups if you have a chance to take a look.
cc @nastra as well @rymurr in case you have any final comments on the doc as it is. I know it's a lot to ingest, but I think if we can get this initial doc in, then we can hopefully make things smaller and begin to follow a more consistent pattern that we'll adapt to as we all work more with OpenAPI.
Please keep in mind this is just the first of many patches and things to get this off the ground, so that work can begin somewhat more parallelized. Also, once we're all working on this API, if things need to be changed for practical reasons etc, I'm not opposed to that. I think those things will become more apparent as we make more progress. 😄
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771763990
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,696 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found - Parent namespace does not exist
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - properties
+ - defaults
+ properties:
+ overrrides:
+ type: object
+ nullable: false
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ nullable: false
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ nullable: false
+ name:
+ type: string
+ nullable: false
+
+ UpdatePropertiesRequest:
+ type: object
+ properties:
+ removables:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ IcebergResponseObject:
+ description: JSON wrapper for all response bodies, with a data object and / or an error object
+ content:
+ application/json:
+ schema:
+ anyOf:
+ - $ref: '#/components/schemas/ResponseDataObject'
+ - $ref: '#/components/schemas/ResponseErrorObject'
+ example: { "data": { ... }, "error": { } }
Review comment:
Done.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771760254
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
Review comment:
In the future, we may want to add a cascade option.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-997120898
> Overall, this looks good to me. I think that one of the main things to do is add consistency since there are a lot of differences that make it hard to consume as the yaml spec. I think that part of the motivation is to not have a huge number of schemas and response types so this is embedding them in some of the routes. But that ends up being a little confusing overall.
Yeah. With the OpenAPI doc, there really is either a choice between a long form document (where everything is spelled out), or a shorter form document that is harder to read if you're not used to looking at OpenAPI docs.
I'll make it more consistent, but I will warn you that the document size will likely double.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771980631
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,834 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
Review comment:
Am I correct that the intent is to wrap all successful responses with `ResponseDataObject`? That doesn't appear to be what happens in this case because the schema of the response doesn't include the `data` layer.
I'm not sure if it would be very easy to adapt these schemas so that each one is wrapped by `ResponseDataObject`. Seems to me that would require some kind of inheritance, but I don't know how you'd do that with OpenAPI. If inheritance and customizing the `data` payload isn't possible, then we'd need to add that layer to every schema (which is already done for error examples, like `NoSuchNamespaceError`).
Modifying every schema doesn't seem worth it. I don't think that the `data` wrapper is very valuable and it would require a lot of additional boilerplate. The wrapper duplicates error codes anyway.
Another option is to add documentation somewhere that wrapping with `ResponseDataObject` is the convention, but I think it would be best if the actual definition matched.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771759934
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
Review comment:
This is simply less overhead than having to repeat all of the layers for `content: application/json: schema` for every single 404 route.
I can do it the way that that `rename` is, but it will make the document a lot larger.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771762340
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
Review comment:
Sure. I received feedback on the last PR to remove those sorts of comments and just leave `Not Found`. For the most part, I left distinguishing comments, but I missed this one.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771759121
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - properties
+ - defaults
+ properties:
+ overrrides:
+ type: object
+ nullable: false
Review comment:
Technically, `nullable` signifies whether or not `null` is an allowed value (outside of whether or not the type of the value, e.g. String, would allow null in general).
But here they're just left over artifacts from before I had them under `required`. I'll remove the `nullable`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771759205
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
Review comment:
The rename route adds the schema and an example:
```
TableToRenameDoesNotExist:
$ref: '#/components/examples/NoSuchTableError'
```
Should this be consistent and do the same here?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771759857
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
Review comment:
Nit: maybe this should be a separate paragraph
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r773506911
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
Review comment:
Yeah. At present we've left it out for simplicity (as there's already been a lot of discussion around just this), so it will be include it in a follow up PR, but there can be a callback URL that a client can subscribe to to get notification messages etc.
https://swagger.io/docs/specification/callbacks/
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r773508843
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
Review comment:
I would personally choose to leave 5xx off of the document. I consider a potential 500 as an implicit response for any HTTP request, as it's possible the request returns 5xx before even reaching the application server.
I personally try to avoid explicitly returning 5xx as part of the normal flow of code, but implicitly all manner of 5xx should be expected. I'm just not sure if it's worth spelling out for every route.
If others think we should include them, I'd be ok with that.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1007769255
I merged this and we can pick up changes from @rymurr's review as we extend this. Thanks @jackye1995 and everyone on the original PR for all the input, and especially to @kbendick for getting this ready!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue merged pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue merged pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1004465913
> @jackye1995, it looks like we're mostly in agreement now:
>
> > 1. if it's better to have specific operation routes for non-RESTful operations
> > 2. head table/namespace operation with response, if we do that what set of fields should be in the response
> > 3. if pagination of response is needed when there are too many metadata log or snapshots
> > 4. progress tracking for table purge
> > 5. drop namespace cascade
>
> For 1, I think we're just trying to decide on the path for the `/tables/rename` route, right? I like the simplicity of `tables` and I don't think it will be confusing to have operation routes there. That's where I'd add multi-table transactions as well, which don't cleanly fit into a single REST resource.
>
> For 2, I think we should remove the HEAD request for namespaces and leave the tables HEAD request without response bodies. We're probably agreed?
>
> 3, 4, and 5 are not strictly required so I like the idea of adding them in follow-ups in parallel. That way we can start iterating on other areas with this as the basis.
I'm in agreement on 1, that `/tables/rename` makes sense to me. It's just referencing tables in general.
I've gone ahead and removed the HEAD request for namespaces. We can always add it back in in the future if need be. I agree that returning the whole table object for an existence check might be relatively expensive, and so it makes sense to keep the HEAD check for tables. I'm still not opposed to adding response bodies to the HEAD requests eventually, but that can be a topic for another day if need be.
And then agreed on 3,4,5. The sooner we can get the initial document in, the sooner we can make smaller changes that are more digestible and can also work more in parallel 😄
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1004452252
> > HEAD requests are not supposed to have a response body
>
> Yes I mean to have another API with a `GET` verb so that it can have a response.
Ahh that makes sense. I'm still not personally opposed to having a response body in a HEAD request, as users can likely ignore it given that it's a HEAD request. And given that there are a number of well used APIs that do have them.
But for now I think it's probably best to put that into the backlog as several people have had strong-ish opinions about it. The "backlog" meaning the work I'll be returning to more or less right after this PR as well as whatever side work I also have going 😄
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1003882451
Thanks for your review @jackye1995
> The big questions I have are:
>
> 1. namespace property, can we just use `PUT namespace` for that
My one concern with using an unqualified `PUT namespace` (unqualified meaning nothing in the path) is that backend frameworks would need to be able to handle any shape of body depending on what is being updated. For namespace, that would only be properties as far as I can tell, so this one might not be too bad.
> 2. `/v1/tables/rename`, can we use `/v1/table-ops/rename` or something else to make the path more self-explanatory
I'm presently against using anything with `table-ops` in the name for now, only as we have had a decent amount of discussion on topics so far, but `table-ops` is still yet to be fully discused.
Can we can mentally mark it as potentially re-namable to `table-ops` or something if we go with that after we discuss more of the routes that involve `table-ops`? I feel like that's going to be a bigger discussion (using most of the `table-ops`).
I also feel that `table-ops` is _maybe_ too resource oriented vs just `tables`, but that's a discussion for `table-ops` in general which I'm sure will be soon.
> 3. I think we do need 5xx and 400 error definitions in the spec based on RFC 7231, and we can simplify the error response using a universal error schema.
Yes we do. I have seen them with exactly `400` and `5xx` (e.g. in the [Confluent Kafka REST OpenAPI spec](https://github.com/confluentinc/kafka-rest/blob/b0259cfae59f68d93c9c32087e1aa96efeec6a74/api/v3/openapi.yaml#L77-L78) I recently found). I will add those tomorrow (more or less just as is on that doc)!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777613900
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
Review comment:
I don't really see a downside to using `tables` here. I don't think it is confusing to have some operations under `tables` and still use a namespace path for individual table operations.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] jackye1995 commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
jackye1995 commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777655658
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ name:
+ type: string
+ nullable: false
+
+ UpdateNamespacePropertiesRequest:
+ type: object
+ properties:
+ removals:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ # Note that this is a representative example response for use as a shorthand in the spec.
+ # The fields `message` and `type` as indicated here are not presently prescriptive.
+ UnauthorizedResponse:
+ description: Unauthorized. The client does not have permissions to call this route.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example: {
+ "error": {
+ "message": "Not authorized to make this request",
+ "type": "NotAuthorizedException",
+ "code": 401
+ }
+ }
+
+ # Note that this is a representative example response for use as a shorthand in the spec.
+ # The fields `message` and `type` as indicated here are not presently prescriptive.
+ UnsupportedOperationResponse:
+ description: Not Acceptable / Unsuported Operation. The server does not support this operation.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example: {
+ "error": {
+ "message": "The server does not support this operation",
+ "type": "UnsupportedOperationException",
+ "code": 406
+ }
+ }
+
+ IcebergErrorResponse:
Review comment:
thanks for the explanation!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r772675742
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,775 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/401UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not provided,
+ all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ schema:
+ type: string
+ example: "accounting"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ $ref: '#/components/responses/401UnauthorizedResponse'
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/401UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/401UnauthorizedResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists. This operation does not return a response body.
+ responses:
+ 200:
+ description: Namesapce exists
Review comment:
Fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771758072
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
Review comment:
Nice to have this deduplication!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771761115
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
Review comment:
What about from the example?
```
multipart_namespace:
value: "accounting%00tax"
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771759378
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
Review comment:
What's the difference between this and the `content` metadata like you use for `rename`? Can we make these consistent?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771766753
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
Review comment:
I'm removing the quotes now on all of them.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r773290024
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,834 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
Review comment:
Yeah, we should definitely remove it. If we can't express that the same wrapper should be used for all of these, then it doesn't make sense to have it. And the utility was dubious anyway.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue edited a comment on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue edited a comment on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1004455929
@jackye1995, it looks like we're mostly in agreement now:
> 1. if it's better to have specific operation routes for non-RESTful operations
> 2. head table/namespace operation with response, if we do that what set of fields should be in the response
> 3. if pagination of response is needed when there are too many metadata log or snapshots
> 4. progress tracking for table purge
> 5. drop namespace cascade
For 1, I think we're just trying to decide on the path for the `/tables/rename` route, right? I like the simplicity of `tables` and I don't think it will be confusing to have operation routes there. That's where I'd add multi-table transactions as well, which don't cleanly fit into a single REST resource.
For 2, I think we should remove the HEAD request for namespaces and leave the tables HEAD request without response bodies. We're probably agreed?
3, 4, and 5 are not strictly required so I like the idea of adding them in follow-ups in parallel. That way we can start iterating on other areas with this as the basis.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] jackye1995 commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
jackye1995 commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1004355932
> HEAD requests are not supposed to have a response body
Yes I mean to have another API with a `GET` verb so that it can have a response.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771761810
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
Review comment:
Yeah. I'm going to move this parameter back up, since it's only used in the one location and is not actually generic.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771761219
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
Review comment:
That's really the only place it's used. I actually considered just leaving it as a parameter in the one spot it's used. but since I didn't, I'll remove that `under which to list namespaces` part.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771762156
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
Review comment:
So the way it is currently, 404 with just a plain description, signifies that there is no response object.
I'm happy to do that (with an example and schema) for all of them, it will just make the document a lot larger. But it is more correct.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771759489
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
Review comment:
There really isn't much of a distinction. It's possible to define a bit more things from within the `schema` section, but I'll check if I actually am using any of those anymore or not.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777764967
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
Review comment:
My dog!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777763420
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
Review comment:
I think it's fine as-is for now. But a lot of libraries seem to allow bodies for HEAD requests. We should consider it in the future though. I know there are "the standard(s)" but quite a number of well used libraries do seem to deviate from them now and then for practical purposes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777771000
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
Review comment:
Okay, since we are not going to add bodies to the HEAD responses, I think that we should remove this. There isn't a significant benefit that I can think of. We can always add it later if someone wants it.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r773507608
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not rturn a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
Review comment:
That's ok. Here, where there's just a response code and a description, in OpenAPI terms that means that there is no response body.
I've done it here for `HEAD` requests, which aren't supposed to return a response body. However, several well-known systems such as S3 still do have a response body with HEAD requests, so we might allow for that anyway.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] jackye1995 commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
jackye1995 commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r774175669
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
Review comment:
nit: `last_modified_time`
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
Review comment:
nit: extra empty line
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
Review comment:
what is `using 'SELECT NAMESPACE IN a'`? If this is not standard SQL sentence I think it's better to not mention it to avoid confusion.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
Review comment:
My understanding is that 409 usually means concurrent conflicts, already exists should be 400 bad request.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
Review comment:
who's Hank? (just curious)
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ name:
+ type: string
+ nullable: false
+
+ UpdateNamespacePropertiesRequest:
+ type: object
+ properties:
+ removals:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ # Note that this is a representative example response for use as a shorthand in the spec.
+ # The fields `message` and `type` as indicated here are not presently prescriptive.
+ UnauthorizedResponse:
+ description: Unauthorized. The client does not have permissions to call this route.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example: {
+ "error": {
+ "message": "Not authorized to make this request",
+ "type": "NotAuthorizedException",
+ "code": 401
+ }
+ }
+
+ # Note that this is a representative example response for use as a shorthand in the spec.
+ # The fields `message` and `type` as indicated here are not presently prescriptive.
+ UnsupportedOperationResponse:
+ description: Not Acceptable / Unsuported Operation. The server does not support this operation.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example: {
+ "error": {
+ "message": "The server does not support this operation",
+ "type": "UnsupportedOperationException",
+ "code": 406
+ }
+ }
+
+ IcebergErrorResponse:
+ description: JSON wrapper for all error responses (non-2xx)
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ error:
+ $ref: '#/components/schemas/StandardErrorWrapper'
+ additionalProperties: false
+ example: {
+ "error": {
+ "message": "The server does not support this operation",
+ "type": "UnsupportedOperationException",
+ "code": 406
+ } }
+
+ DropTableResponse:
+ description: A successful call to drop a table
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ dropped:
+ type: boolean
+ description: true if the table was found and removed from the catalog
+ purged:
+ type: boolean
+ description: whether the underlying data was purged or is being purged
+
+ DropNamespaceResponse:
+ description: A successful call to drop a namespace
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ dropped:
+ description: true if the namespace was dropped
+ type: boolean
+
+ GetNamespaceResponse:
+ description:
+ Returns a namespace, as well as any properties stored on the namespace if namespace properties
+ are supported by the server.
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description:
+ Properties stored on the namespace, if supported by the server.
+ If the server does not support namespace properties, it should return null for this field.
+ If namespace properties are supported, but none are set, it should return an empty object.
+ example: { "owner": "Ralph", 'transient_lastDdlTime': '1452120468' }
+ default: { }
+ nullable: true
+
+ ListTablesResponse:
+ description: A list of table identifiers
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ uniqueItems: true
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ ListNamespacesResponse:
+ description: A list of namespaces
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ uniqueItems: true
+ items:
+ $ref: '#/components/schemas/Namespace'
+
+ UpdateNamespacePropertiesResponse:
+ description: JSON data response for a synchronous update properties request.
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - updated
Review comment:
I think these should not be required, because you might have only updates or removes.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ name:
+ type: string
+ nullable: false
+
+ UpdateNamespacePropertiesRequest:
+ type: object
+ properties:
+ removals:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ # Note that this is a representative example response for use as a shorthand in the spec.
+ # The fields `message` and `type` as indicated here are not presently prescriptive.
+ UnauthorizedResponse:
+ description: Unauthorized. The client does not have permissions to call this route.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example: {
+ "error": {
+ "message": "Not authorized to make this request",
+ "type": "NotAuthorizedException",
+ "code": 401
+ }
+ }
+
+ # Note that this is a representative example response for use as a shorthand in the spec.
+ # The fields `message` and `type` as indicated here are not presently prescriptive.
+ UnsupportedOperationResponse:
+ description: Not Acceptable / Unsuported Operation. The server does not support this operation.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example: {
+ "error": {
+ "message": "The server does not support this operation",
+ "type": "UnsupportedOperationException",
+ "code": 406
+ }
+ }
+
+ IcebergErrorResponse:
Review comment:
if we have this one, why do we need to define the other error responses? My intention is that if we only have a very generic data model defined in open API spec, we don't need to spend effort to keep the error classes in Java and the response here always in sync.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
Review comment:
Maybe I missed the discussion last time, but I still don't understand why we cannot use `PUT /v1/namespaces/{namespace}` for this. I would assume if we have some special properties for namespace in the future, we still want to have the ability to update that anyway.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
Review comment:
I also think it's better to use more meaningful examples, like `engineering.cs.faculties` instead of `a.b.t`
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
Review comment:
why not just `source` and `destination`? Identifier is already inferred from the schema definition.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
Review comment:
in that case, I feel it's better to use POST `/v1/tables/head` to express such operation, otherwise I am not sure what is going to happen for an open-api generated client.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
Review comment:
I don't think they should be required, because the server might return null for one or both of them.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
Review comment:
Also, why is this named differently from the other responses that are of format `XxxxResponse`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777616651
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ name:
+ type: string
+ nullable: false
+
+ UpdateNamespacePropertiesRequest:
+ type: object
+ properties:
+ removals:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ # Note that this is a representative example response for use as a shorthand in the spec.
+ # The fields `message` and `type` as indicated here are not presently prescriptive.
+ UnauthorizedResponse:
+ description: Unauthorized. The client does not have permissions to call this route.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example: {
+ "error": {
+ "message": "Not authorized to make this request",
+ "type": "NotAuthorizedException",
+ "code": 401
+ }
+ }
+
+ # Note that this is a representative example response for use as a shorthand in the spec.
+ # The fields `message` and `type` as indicated here are not presently prescriptive.
+ UnsupportedOperationResponse:
+ description: Not Acceptable / Unsuported Operation. The server does not support this operation.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example: {
+ "error": {
+ "message": "The server does not support this operation",
+ "type": "UnsupportedOperationException",
+ "code": 406
+ }
+ }
+
+ IcebergErrorResponse:
Review comment:
The other responses are used to shorten the docs. There are two patterns:
1. Use a common response that has the example and description
2. Use this schema and add custom examples and descriptions
Since 401 never changes, it can use the first pattern. But response codes like 404 use the second pattern because the examples change, like no such table and no such namespace examples.
I think it works to minimize duplication the way @kbendick has it now.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777620121
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation is not required to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ StandardErrorWrapper:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
Review comment:
I think whether the responses are required depends on whether you're thinking about how to implement the client or the server. It's easier to be able to leave out part of the response on the service, but that pushes more responsibility to the client. It's easier for the client to be able to rely on the list being non-null. When choosing between the two, I'd lean toward making it simpler for the client rather than the server because we expect fewer server implementations and higher quality adherence to the spec.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] jackye1995 commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
jackye1995 commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r774175669
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
Review comment:
nit: `last_modified_time` with backquote
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rymurr commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rymurr commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1007265607
Please don't wait for me. I will get to it next week and we can do a follow
up if I raise anything.
On Thu, Jan 6, 2022 at 6:21 AM Kyle Bendickson ***@***.***>
wrote:
> @rymurr <https://github.com/rymurr>, any comments? We'd like to start
> working on the follow ups if you have a chance to take a look.
>
> cc @nastra <https://github.com/nastra> as well @rymurr
> <https://github.com/rymurr> in case you have any final comments on the
> doc as it is. I know it's a lot to ingest, but I think if we can get this
> initial doc in, then we can hopefully make things smaller and begin to
> follow a more consistent pattern that we'll adapt to as we all work more
> with OpenAPI.
>
> Please keep in mind this is just the first of many patches and things to
> get this off the ground, so that work can begin somewhat more parallelized.
> Also, once we're all working on this API, if things need to be changed for
> practical reasons etc, I'm not opposed to that. I think those things will
> become more apparent as we make more progress. 😄
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/apache/iceberg/pull/3770#issuecomment-1006293595>, or
> unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AAPNXIL4GEPQKYMPM3KLX53UUURGTANCNFSM5KJ7LIWA>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771760162
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - defaults
+ - overrides
+ properties:
+ overrrides:
+ type: object
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ name:
+ type: string
+ nullable: false
+
+ UpdatePropertiesRequest:
+ type: object
+ properties:
+ removables:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ 404Response:
+ description: Generic example response to demonstrate a 404's general form.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example: {
+ "error": {
+ "message": "The given namespace does not exist",
+ "type": "NoSuchNamespaceException",
+ "code": 404
+ }
+ }
+
+ IcebergResponseObject:
+ description: JSON wrapper for all response bodies, with a data object and / or an error object
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ data:
+ $ref: '#/components/schemas/ResponseDataObject'
+ error:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example: { "data": { ... }, "error": { } }
+
+ DropTableResponse:
+ description: A successful call to drop a table
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ dropped:
+ type: boolean
+ description: true if the table was found and removed from the catalog
+ purged:
+ type: boolean
+ description: whether the underlying data was purged or is being purged
+
+ GetNamespaceResponse:
+ description: Returns a namespace and the properties stored on it
Review comment:
This should probably mention that if properties are not supported the properties are optional? Or maybe they must be sent but can be empty?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771760987
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - properties
+ - defaults
+ properties:
+ overrrides:
+ type: object
+ nullable: false
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ nullable: false
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ nullable: false
+ name:
+ type: string
+ nullable: false
+
+ UpdatePropertiesRequest:
+ type: object
+ properties:
+ removables:
Review comment:
Removed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771758422
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
Review comment:
I think we should remove `%00` here, but not from the example. The problem having it here is that we don't want people actually creating the string `accounting%00tax` and then URL encoding it to produce `accounting%2500tax`. Just saying `null byte` here is clear enough.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771772202
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
Review comment:
Found a way to do it without making the document _too much_ larger. There are some quirks to working with an Open API doc I didn't know before so settling on what should be standardized will be helpful.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771757117
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,696 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found - Parent namespace does not exist
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - properties
+ - defaults
+ properties:
+ overrrides:
+ type: object
+ nullable: false
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ nullable: false
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ nullable: false
+ name:
+ type: string
+ nullable: false
+
+ UpdatePropertiesRequest:
+ type: object
+ properties:
+ removables:
+ type: array
+ uniqueItems: true
+ items:
+ type: string
+ example: '[ "department", "access_group" ]'
+ updates:
+ uniqueItems: true
+ type: object
+ items:
+ type: string
+ example: { "owner": "Hank Bendickson" }
+
+
+ #############################
+ # Reusable Response Objects #
+ #############################
+ responses:
+
+ IcebergResponseObject:
+ description: JSON wrapper for all response bodies, with a data object and / or an error object
+ content:
+ application/json:
+ schema:
+ anyOf:
+ - $ref: '#/components/schemas/ResponseDataObject'
+ - $ref: '#/components/schemas/ResponseErrorObject'
+ example: { "data": { ... }, "error": { } }
Review comment:
This example doesn't appear to be correct. The `ResponseErrorObject` doesn't define an `error` object. It defines `message`, `type`, and `code`.
Maybe it would be good to have this object define the `data` and `error` keys that have types `ResponseDataObject` and `ResponseErrorObject` respectively?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771758024
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
Review comment:
Should these responses go under `responses`? Is there a distinction?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771771241
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,775 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/401UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not provided,
+ all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ schema:
+ type: string
+ example: "accounting"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ $ref: '#/components/responses/401UnauthorizedResponse'
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/401UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/401UnauthorizedResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists. This operation does not return a response body.
+ responses:
+ 200:
+ description: Namesapce exists
Review comment:
Typo: Namespace
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r772676741
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,834 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
Review comment:
Yeah that was the intent, but I haven't settled on a good way to show that.
Some people have suggested getting rid of it, and having success responses not wrapped in a standard wrapper (which would be like it currently is). Which is why I've left it as is.
I'll count yours as the final vote against having the `data` wrapper and will remove that entirely. Success responses will just be the JSON object (like `DropNamespaceResponse`), but the error responses will all have the same standard error wrapper.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick edited a comment on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick edited a comment on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1004309804
Thanks for the pending thoughts @jackye1995! I'll respond a bit, and then we'll keep these for later discussion as well (assuming there will be more discussion groups / follow up PRs etc)
> 1. if it's better to have specific operation routes for non-RESTful operations
Agreed.
> 2. head table/namespace operation with response, if we do that what set of fields should be in the response
So currently, there's no set of fields in the response for HEAD requests. That's what the response code and just the string `description` represents. Technically, HEAD requests are not supposed to have a response body. However, so many famous APIs do that I think we can add them in a follow up.
> 3. if pagination of response is needed when there are too many metadata log or snapshots
I had brought up pagination for one or two routes, but it was deemed as somewhat premature. I think eventually we will definitely need some kind of pagination for sure.
> 4. progress tracking for table purge
Will be coming in a follow up.
> 5. drop namespace cascade
That one is not currently implemented, but I agree. Once we finish implementing it, it should be easy to add in. We can start considering where to put it in the API here sooner. Probably as a query parameter I would think.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1004450415
> Overall, this looks good to me. I think that one of the main things to do is add consistency since there are a lot of differences that make it hard to consume as the yaml spec. I think that part of the motivation is to not have a huge number of schemas and response types so this is embedding them in some of the routes. But that ends up being a little confusing overall.
Another thing I only recently discovered is that many of these things can be split across several files. A CLI tool is then used to bundle them together if need be, but it might be good to consider that in the future to make consuming an ever-growing document a lot simpler.
Not going to do that for now as that's probably something to discuss (it does add complexity as well for the reader), but it might be something we can find a trade off for.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777771217
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
Review comment:
Let's add the better example. I like that.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777763876
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
Review comment:
I pulled this directly from the JavaDoc comment, but I can use a more realistic example like I did elsewhere (`accounting.tax` is what I tended to use elsewhere).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1003882891
> Thanks for your review @jackye1995
>
> > The big questions I have are:
> >
> > 1. namespace property, can we just use `PUT namespace` for that
>
> My one concern with using an unqualified `PUT namespace` (unqualified meaning nothing in the path representing that it's a `properties` request) is that backend frameworks would need to be able to handle any shape of body depending on what is being updated. For namespace, that would only be properties as far as I can tell, so this one might not be too bad. But for `tables` etc, that could get unwieldy and I don't love the idea of using a plain `PUT` for namespace and then not necessarily doing that for tables etc. The `PUT namespaces` would still more or less need to have the same body to differentiate between properties to remove and properties to upsert.
>
> > 2. `/v1/tables/rename`, can we use `/v1/table-ops/rename` or something else to make the path more self-explanatory
>
> I'm presently against using anything with `table-ops` in the name for now, only as we have had a decent amount of discussion on topics so far, but `table-ops` is still yet to be fully discused.
>
> Can we can mentally mark it as potentially re-namable to `table-ops` or something if we go with that after we discuss more of the routes that involve `table-ops`? I feel like that's going to be a bigger discussion (using most of the `table-ops`).
>
> I also feel that `table-ops` is _maybe_ too resource oriented vs just `tables`, but that's a discussion for `table-ops` in general which I'm sure will be soon.
>
> > 3. I think we do need 5xx and 400 error definitions in the spec based on RFC 7231, and we can simplify the error response using a universal error schema.
>
> Yes we do. I have seen them with exactly `400` and `5xx` (e.g. in the [Confluent Kafka REST OpenAPI spec](https://github.com/confluentinc/kafka-rest/blob/b0259cfae59f68d93c9c32087e1aa96efeec6a74/api/v3/openapi.yaml#L77-L78) I recently found). I will add those tomorrow (more or less just as is on that doc)!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r773513125
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
Review comment:
@rymurr and @jackye1995, what do you think about adding a body to the HEAD responses? I think it would be nice to do for consistency.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r773463088
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,834 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
Review comment:
`ResponseDataWrapper` has been removed. There's now a schama `StandardErrorWrapper`, which has the `message`, `type`, `code` fields.
And then there's a response object, `IcebergErrorResponse` under `responses` which makes the response into `{ "error": { ... fields from error wrapper ... }`.
The success responses have no wrapper, and use their top level defined responses.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771757347
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,696 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found - Parent namespace does not exist
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - properties
Review comment:
I don't see anything under `properties:` in the YAML that is named `properties`. Did you mean for `overrides` and `defaults` to both be required?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771764046
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
Review comment:
Ultimately, this isn't a generic parameter at the moment, so I moved it back to the one route where it is used. If we find need of it to be a generic parameter in the future, then we can deal with that then.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771764434
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
Review comment:
Updated.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771757778
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - properties
+ - defaults
+ properties:
+ overrrides:
+ type: object
+ nullable: false
Review comment:
Are these `nullable` settings needed? The property is already required and has a type.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
+ operationId: renameTable
+ requestBody:
+ description: Current table identifier to rename and new table identifier to rename to
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RenameTableRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 404:
+ description:
+ Not Found
+ - NoSuchTableException, Table to rename does not exist
+ - NoSuchNamespaceException, The target namespace of the new table identifier does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ NamespaceToRenameToDoesNotExist:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 409:
+ description: Conflict - The target table identifier to rename to already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ example:
+ $ref: '#/components/examples/TableAlreadyExistsError'
+
+components:
+ #######################################################
+ # Common Parameter Definitions Used In Several Routes #
+ #######################################################
+ parameters:
+ namespace:
+ name: namespace
+ in: path
+ required: true
+ description:
+ A namespace identifier as a single string.
+ Multipart namespace parts should be separated by the null byte, %00.
+ schema:
+ type: string
+ examples:
+ singlepart_namespace:
+ value: "accounting"
+ multipart_namespace:
+ value: "accounting%00tax"
+
+ table:
+ name: table
+ in: path
+ description: A table name
+ required: true
+ schema:
+ type: string
+ example: "sales"
+
+ parent:
+ name: parent
+ in: query
+ description:
+ Optional parent namespace under which to list namespaces.
+ If parent is a multipart namespace, the parts must be separated by the null byte, %00.
+ When empty, list top-level namespaces.
+ required: false
+ schema:
+ type: string
+ example: "accounting%00tax"
+
+ ##############################
+ # Application Schema Objects #
+ ##############################
+ schemas:
+
+ ResponseDataObject:
+ type: object
+ description: JSON data payload returned in a successful response body
+ properties:
+ data:
+ type: object
+ description: Wrapper for the response of a successful request
+ example: { "data": { ... } }
+
+ ResponseErrorObject:
+ type: object
+ description: JSON error payload returned in a response with further details on the error
+ required:
+ - message
+ - type
+ - code
+ properties:
+ message:
+ type: string
+ description: Human-readable error message
+ type:
+ type: string
+ description: Internal type definition of the error
+ example: NoSuchNamespaceException
+ code:
+ type: integer
+ minimum: 400
+ maximum: 600
+ description: HTTP response code
+ example: 404
+
+ CatalogConfiguration:
+ type: object
+ description: Server-provided configuration for the catalog.
+ required:
+ - properties
+ - defaults
+ properties:
+ overrrides:
+ type: object
+ nullable: false
+ description:
+ Properties that should be used to override client configuration; applied after defaults and client configuration.
+ defaults:
+ type: object
+ nullable: false
+ description:
+ Properties that should be used as default configuration; applied before client configuration.
+
+ CreateNamespaceRequest:
+ type: object
+ required:
+ - namespace
+ properties:
+ namespace:
+ $ref: '#/components/schemas/Namespace'
+ properties:
+ type: object
+ description: Configured string to string map of properties for the namespace
+ example: '{ "owner": "Hank Bendickson" }'
+ default: '{ }'
+
+ Namespace:
+ description: Reference to one or more levels of a namespace
+ type: array
+ items:
+ type: string
+ example: [ "accounting", "tax" ]
+
+ RenameTableRequest:
+ type: object
+ properties:
+ sourceTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+ destinationTableIdentifier:
+ $ref: '#/components/schemas/TableIdentifier'
+
+ TableIdentifier:
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: array
+ description: Individual levels of the namespace
+ items:
+ type: string
+ nullable: false
+ name:
+ type: string
+ nullable: false
+
+ UpdatePropertiesRequest:
+ type: object
+ properties:
+ removables:
Review comment:
Let's go with `removals` instead. I just wouldn't use the `-able` suffix here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771758748
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
+ post:
+ tags:
+ - Catalog API
+ summary: Rename a table from its current name to a new name
+ description:
+ Rename a table from one identifier to another. It's valid to move a table
+ across namespaces, but the server implementation doesn't need to support it.
Review comment:
How about "is not required to support it"
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r771979721
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
Review comment:
Yeah, we wanted to avoid boolean parameters on the catalog API where we could. The problem here is that it would be really inefficient to use the rest of this API to do a cascading drop because the client would need potentially hundreds of requests to drop each table and namespace individually, and the requests have relatively high latency. We may want to add a cascade flag to the catalog API as well, or a new method (`dropNamespaceCascade`).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] jackye1995 commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
jackye1995 commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r774184360
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
Review comment:
actually I realize some places have extra lines for each HTTP verb section, and some don't, just make sure it's consistent.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] jackye1995 commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
jackye1995 commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r774189302
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
Review comment:
I did some research for this, and in RFC 7231 (https://datatracker.ietf.org/doc/html/rfc7231#section-6.6):
> The 5xx (Server Error) class of status code indicates that the server
is aware that it has erred or is incapable of performing the
requested method. Except when responding to a HEAD request, the
server SHOULD send a representation containing an explanation of the
error situation, and whether it is a temporary or permanent
So I think it's better to define that.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove properties on a namespace.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
+ examples:
+ UpdateAndRemoveProperties:
+ $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ 406:
+ $ref: '#/components/responses/UnsupportedOperationResponse'
+ 422:
+ description: Unprocessable Entity - A property key was included in both `removals` and `updates`
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ UnprocessableEntityDuplicateKey:
+ $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListTablesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListTablesNonEmptyExample'
+ EmptyNamespaceResponse:
+ $ref: '#/components/examples/ListTablesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - The namespace specified does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description:
+ Not Found - NoSuchTableException, Table to drop does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ TableToRenameDoesNotExist:
+ $ref: '#/components/examples/NoSuchTableError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace. This request does not return a response body.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ /v1/tables/rename:
Review comment:
I wonder if we can use a different word from `tables` for action paths, because `tables` already means a table resource in the REST-based path. Using another word like `table-ops` might be more self-explanatory for the purpose of the route.
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
Review comment:
looks like we are missing 400 bad request for all requests?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] kbendick commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
kbendick commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r773489433
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,712 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ description: Unauthorized
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate into
+ `GET /namespaces?parent=a` and must return a namespace, ["a", "b"].
+ operationId: listNamespaces
+ parameters:
+ - $ref: '#/components/parameters/parent'
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ namespaces:
+ type: array
+ items:
+ $ref: '#/components/schemas/Namespace'
+ 401:
+ description: Unauthorized
+ 404:
+ $ref: '#/components/responses/404Response'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ required: true
+ responses:
+ 200:
+ description: OK
+ 401:
+ description: Unauthorized
+ 409:
+ description: Conflict - The namespace already exists.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 404:
+ description: Not Found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description: Check if a namespace exists.
+ responses:
+ '200':
+ description: Namesapce exists
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergResponseObject'
+ example: { "data": { "dropped": true } }
+ '401':
+ description: Unauthorized
+ '404':
+ description: Not Found
+
+
+ /v1/namespaces/{namespace}/properties:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ post:
+ tags:
+ - Catalog API
+ summary: Set or remove properties on a namespace
+ operationId: updateProperties
+ description:
+ Set and/or remove a collection or properties on a namespae.
+ The request body specifies a list of properties to remove and a map
+ of key value pairs to update.
+
+ Properties that are not in the request are not modified or removed by this call.
+ Server implementations are not required to support namespace properties.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdatePropertiesRequest'
+ example:
+ { "removables": [ "foo", "bar" ], "updates": { "owner": "Raoul" } }
+ required: true
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/UpdatePropertiesResponse'
+ example: {
+ "updated": [ "owner" ],
+ "removed": [ "foo" ],
+ "missing": [ "bar" ]
+ }
+ 404:
+ description: Not Found
+ 406:
+ description: Not Acceptable - Unsupported Operation
+ 422:
+ description: Unprocessable Entity - A property key was included in both removables and updates
+
+ /v1/namespaces/{namespace}/tables:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: List all table identifiers underneath a given namespace
+ description: Return all table identifiers under this namespace
+ operationId: listTables
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ identifiers:
+ type: array
+ items:
+ $ref: '#/components/schemas/TableIdentifier'
+ examples:
+ TableIdentifierListExample:
+ $ref: '#/components/examples/ListTablesExample'
+ 404:
+ description: Not Found - Either the namespace or the table does not exist
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ examples:
+ NamespaceNotFound:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ TableNotFound:
+ $ref: '#/components/examples/NoSuchTableError'
+
+ /v1/namespaces/{namespace}/tables/{table}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ - $ref: '#/components/parameters/table'
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a table from the catalog
+ operationId: dropTable
+ description: Remove a table from the catalog
+ parameters:
+ - name: purgeRequested
+ in: query
+ required: false
+ description: Whether the user requested to purge the underlying table's data and metadata
+ schema:
+ type: boolean
+ default: false
+ responses:
+ 200:
+ description: OK
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/responses/DropTableResponse'
+ example: { "dropped": true, "purged": false }
+ 202:
+ description: Accepted - for use if purgeRequested is implemented as an asynchronous action.
+ 404:
+ $ref: '#/components/schemas/ResponseErrorObject'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a table exists
+ operationId: tableExists
+ description:
+ Check if a table exists within a given namespace.
+ responses:
+ 200:
+ description: OK - Table Exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
Review comment:
OK. I've updated most everything to use non-inlined examples.
This section above uses `description` only to indicate that there is no response body (as it's a HEAD request).
We might choose to deviate from the standard and allow a response body on `HEAD` responses (like many systems do, including S3's API), at which time I'll update these from simple `Description` and status codes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] jackye1995 commented on pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
jackye1995 commented on pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#issuecomment-1004304930
> I'm presently against using anything with table-ops in the name for now, only as we have had a decent amount of discussion on topics so far, but table-ops is still yet to be fully discused.
Sure. In that case the only big thing I see currently missing is the 400 response, I will approve when that is added.
Some pending discussions in my mind after this PR are:
1. if it's better to have specific operation routes for non-RESTful operations
2. head table/namespace operation with response, if we do that what set of fields should be in the response
3. if pagination of response is needed when there are too many metadata log or snapshots
4. progress tracking for table purge
5. drop namespace cascade
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] jackye1995 commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
jackye1995 commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777646881
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
Review comment:
thanks for the explanation!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
[GitHub] [iceberg] rdblue commented on a change in pull request #3770: Spec: Initial OpenAPI Spec for a Rest Catalog
Posted by GitBox <gi...@apache.org>.
rdblue commented on a change in pull request #3770:
URL: https://github.com/apache/iceberg/pull/3770#discussion_r777611438
##########
File path: rest_docs/rest-catalog-open-api.yaml
##########
@@ -0,0 +1,849 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+openapi: 3.0.3
+info:
+ title: Apache Iceberg REST Catalog API
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+ version: 0.0.1
+ description:
+ Defines the specification for the first version of the REST Catalog API.
+ Implementations should ideally support both Iceberg table specs v1 and v2, with priority given to v2.
+servers:
+ - url: "{scheme}://{host}/{basePath}"
+ description: Server URL when the port can be inferred from the scheme
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+ - url: "{scheme}://{host}:{port}/{basePath}"
+ description: Generic base server URL, with all parts configurable
+ variables:
+ scheme:
+ description: The scheme of the URI, either http or https.
+ default: https
+ host:
+ description: The host address for the specified server
+ default: localhost
+ port:
+ description: The port used when addressing the host
+ default: "443"
+ basePath:
+ description: Optional prefix to be appended to all routes
+ default: ""
+# All routes are currently configured using an Authorization header.
+security:
+ - BearerAuth: []
+paths:
+ /v1/config:
+ get:
+ tags:
+ - Configuration API
+ summary: List all catalog configuration settings
+ operationId: getConfig
+ description:
+ "
+ All REST clients should first call this route to get catalog configuration
+ properties from the server to configure the catalog and its HTTP client.
+ Configuration from the server consists of two sets of key/value pairs.
+
+ - defaults - properties that should be used as default configuration; applied before client configuration
+
+ - overrides - properties that should be used to override client configuration; applied after defaults and client configuration
+
+
+ Catalog configuration is constructed by setting the defaults, then client-
+ provided configuration, and finally overrides. The final property set is then
+ used to configure the catalog.
+
+
+ For example, a default configuration property might set the size of the
+ client pool, which can be replaced with a client-specific setting. An
+ override might be used to set the warehouse location, which is stored
+ on the server rather than in client configuration.
+
+
+ Common catalog configuration settings are documented at
+ https://iceberg.apache.org/configuration/#catalog-properties
+ "
+ responses:
+ 200:
+ description: Server specified configuration values.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CatalogConfiguration'
+ example: {
+ "data": {
+ "overrides": {
+ "warehouse": "s3://bucket/warehouse/"
+ },
+ "defaults": {
+ "clients": "4"
+ }
+ }
+ }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+
+ /v1/namespaces:
+ get:
+ tags:
+ - Catalog API
+ summary: List namespaces, optionally providing a parent namespace to list underneath
+ description:
+ List all namespaces at a certain level, optionally starting from a given parent namespace.
+ For example, if table a.b.t exists, using 'SELECT NAMESPACE IN a' this would translate
+ into `GET /namespaces?parent=a` and must return a namespace, ["a", "b"]. If `parent` is not
+ provided, all top-level namespaces should be listed.
+ operationId: listNamespaces
+ parameters:
+ - name: parent
+ in: query
+ description:
+ An optional namespace, underneath which to list namespaces.
+ If not provided or empty, all top-level namespaces should be listed.
+ If parent is a multipart namespace, the parts must be separated by the null byte.
+ required: false
+ allowEmptyValue: true
+ schema:
+ type: string
+ example: "accounting%00tax"
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/ListNamespacesResponse'
+ examples:
+ NonEmptyResponse:
+ $ref: '#/components/examples/ListNamespacesNonEmptyExample'
+ EmptyResponse:
+ $ref: '#/components/examples/ListNamespacesEmptyExample'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace provided in the `parent` query parameter is not found.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ post:
+ tags:
+ - Catalog API
+ summary: Create a namespace
+ description:
+ Create a namespace, with an optional set of properties.
+ The server might also add properties, such as last_modified_time etc.
+ operationId: createNamespace
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateNamespaceRequest'
+ responses:
+ 200:
+ description: OK
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 409:
+ description: Conflict - The namespace already exists
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NamespaceAlreadyExists:
+ $ref: '#/components/examples/NamespaceAlreadyExistsError'
+
+ /v1/namespaces/{namespace}:
+ parameters:
+ - $ref: '#/components/parameters/namespace'
+ get:
+ tags:
+ - Catalog API
+ summary: Load the metadata properties for a namespace
+ operationId: loadNamespaceMetadata
+ description: Return all stored metadata properties for a given namespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/GetNamespaceResponse'
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+ head:
+ tags:
+ - Catalog API
+ summary: Check if a namespace exists
+ operationId: namespaceExists
+ description:
+ Check if a namespace exists.
+ This operation does not presently return a response body, which is why the response codes have only
+ a description field.
+ responses:
+ 200:
+ description: Namespace exists
+ 401:
+ description: Unauthorized
+ 404:
+ description: Not Found
+
+ delete:
+ tags:
+ - Catalog API
+ summary: Drop a namespace from the catalog. Namespace must be empty.
+ operationId: dropNamespace
+ responses:
+ 200:
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/DropNamespaceResponse'
+ example: { "dropped": true }
+ 401:
+ $ref: '#/components/responses/UnauthorizedResponse'
+ 404:
+ description: Not Found - Namespace to delete does not exist.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/responses/IcebergErrorResponse'
+ examples:
+ NoSuchNamespaceExample:
+ $ref: '#/components/examples/NoSuchNamespaceError'
+
+ /v1/namespaces/{namespace}/properties:
Review comment:
My takeaway from the discussion was that `PUT` is typically used to set the entire state and should be idempotent. If we were specifically setting the properties to a specific set, `PUT` would be appropriate. Since we are sending changes and not the complete state, `POST` is better so that it is more clear what is happening.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org