This is an automated email from the ASF dual-hosted git repository.
jshao pushed a commit to branch branch-0.6
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/branch-0.6 by this push:
new 3c5f431ed [#2242] docs(open-api): Add the open-api for access control
(#4539)
3c5f431ed is described below
commit 3c5f431eda400300a9ec35dfafa4b8e4716b400f
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Thu Aug 15 20:43:57 2024 +0800
[#2242] docs(open-api): Add the open-api for access control (#4539)
### What changes were proposed in this pull request?
Add the open-api for access control.
### Why are the changes needed?
Fix: #2242
### Does this PR introduce _any_ user-facing change?
No.
### How was this patch tested?
By hand.
Co-authored-by: roryqi <[email protected]>
---
docs/open-api/groups.yaml | 191 +++++++++++++++++++++++++
docs/open-api/openapi.yaml | 110 +++++++++++++++
docs/open-api/owners.yaml | 176 +++++++++++++++++++++++
docs/open-api/permissions.yaml | 262 ++++++++++++++++++++++++++++++++++
docs/open-api/roles.yaml | 311 +++++++++++++++++++++++++++++++++++++++++
docs/open-api/users.yaml | 191 +++++++++++++++++++++++++
6 files changed, 1241 insertions(+)
diff --git a/docs/open-api/groups.yaml b/docs/open-api/groups.yaml
new file mode 100644
index 000000000..f21226b10
--- /dev/null
+++ b/docs/open-api/groups.yaml
@@ -0,0 +1,191 @@
+#
+# 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.
+#
+
+---
+
+paths:
+
+ /metalakes/{metalake}/groups:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+
+ post:
+ tags:
+ - access control
+ summary: Add group
+ operationId: addGroup
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/GroupAddRequest"
+ examples:
+ GroupAddRequest:
+ $ref: "#/components/examples/GroupAddRequest"
+
+ responses:
+ "200":
+ description: Returns the added group object
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "#/components/responses/GroupResponse"
+ examples:
+ GroupResponse:
+ $ref: "#/components/examples/GroupResponse"
+ "409":
+ description: Conflict - The target group already exists in the
specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ GroupAlreadyExistsException:
+ $ref: "#/components/examples/GroupAlreadyExistsException"
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+ /metalakes/{metalake}/groups/{group}:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+ - $ref: "./openapi.yaml#/components/parameters/group"
+
+ get:
+ tags:
+ - access control
+ summary: Get group
+ operationId: getGroup
+ description: Returns the specified group information in the specified
metalake
+ responses:
+ "200":
+ description: Returns the group object
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "#/components/responses/GroupResponse"
+ examples:
+ GroupResponse:
+ $ref: "#/components/examples/GroupResponse"
+ "404":
+ description: Not Found - The specified group does not exist in the
specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ NoSuchMetalakeException:
+ $ref:
"./metalakes.yaml#/components/examples/NoSuchMetalakeException"
+ NoSuchGroupException:
+ $ref: "#/components/examples/NoSuchGroupException"
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+ delete:
+ tags:
+ - access control
+ summary: Remove group
+ operationId: removeGroup
+ responses:
+ "200":
+ $ref: "./openapi.yaml#/components/responses/RemoveResponse"
+ "400":
+ $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+components:
+
+ schemas:
+ Group:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ description: The name of the group
+ roles:
+ type: array
+ items:
+ type: string
+ description: The roles of the group
+ audit:
+ $ref: "./openapi.yaml#/components/schemas/Audit"
+
+ GroupAddRequest:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ description: The name of the group
+
+ responses:
+ GroupResponse:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Status code of the response
+ enum:
+ - 0
+ group:
+ $ref: "#/components/schemas/Group"
+
+ examples:
+ GroupAddRequest:
+ value: {
+ "name": "group1",
+ }
+
+ GroupResponse:
+ value: {
+ "code": 0,
+ "group": {
+ "name": "group1",
+ "roles": [],
+ "audit": {
+ "creator": "gravitino",
+ "createTime": "2023-12-08T06:41:25.595Z"
+ },
+ }
+ }
+
+ GroupAlreadyExistsException:
+ value: {
+ "code": 1004,
+ "type": "GroupAlreadyExistsException",
+ "message": "Group already exists",
+ "stack": [
+ "org.apache.gravitino.exceptions.GroupAlreadyExistsException: Group
already exists: group1"
+ ]
+ }
+
+ NoSuchGroupException:
+ value: {
+ "code": 1003,
+ "type": "NoSuchGroupException",
+ "message": "Group does not exist",
+ "stack": [
+ "org.apache.gravitino.exceptions.NoSuchGroupException: Group does
not exist",
+ "..."
+ ]
+ }
\ No newline at end of file
diff --git a/docs/open-api/openapi.yaml b/docs/open-api/openapi.yaml
index 16eb47ff9..edac71ec6 100644
--- a/docs/open-api/openapi.yaml
+++ b/docs/open-api/openapi.yaml
@@ -109,6 +109,40 @@ paths:
/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/topics/{topic}:
$ref:
"./topics.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1catalogs~1%7Bcatalog%7D~1schemas~1%7Bschema%7D~1topics~1%7Btopic%7D"
+
+ /metalakes/{metalake}/users:
+ $ref: "./users.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1users"
+
+ /metalakes/{metalake}/users/{user}:
+ $ref: "./users.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1users~1%7Buser%7D"
+
+ /metalakes/{metalake}/groups:
+ $ref: "./groups.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1groups"
+
+ /metalakes/{metalake}/groups/{group}:
+ $ref:
"./groups.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1groups~1%7Bgroup%7D"
+
+ /metalakes/{metalake}/roles:
+ $ref: "./roles.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1roles"
+
+ /metalakes/{metalake}/roles/{role}:
+ $ref: "./roles.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1roles~1%7Brole%7D"
+
+ /metalakes/{metalake}/owners/{metadataObjectType}/{metadataObjectFullName}:
+ $ref:
"./owners.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1owners~1%7BmetadataObjectType%7D~1%7BmetadataObjectFullName%7D"
+
+ /metalakes/{metalake}/permissions/users/{user}/grant:
+ $ref:
"./permissions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1permissions~1users~1%7Buser%7D~1grant"
+
+ /metalakes/{metalake}/permissions/users/{user}/revoke:
+ $ref:
"./permissions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1permissions~1users~1%7Buser%7D~1revoke"
+
+ /metalakes/{metalake}/permissions/groups/{group}/grant:
+ $ref:
"./permissions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1permissions~1groups~1%7Bgroup%7D~1grant"
+
+ /metalakes/{metalake}/permissions/groups/{group}/revoke:
+ $ref:
"./permissions.yaml#/paths/~1metalakes~1%7Bmetalake%7D~1permissions~1groups~1%7Bgroup%7D~1revoke"
+
components:
schemas:
@@ -254,6 +288,57 @@ components:
type: boolean
description: Whether the drop operation was successful
+ RemoveResponse:
+ description: Represents a response for a remove operation
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Status code of the response
+ enum:
+ - 0
+ removed:
+ type: boolean
+ description: Whether the remove operation was successful
+
+ DeleteResponse:
+ description: Represents a response for a delete operation
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Status code of the response
+ enum:
+ - 0
+ deleted:
+ type: boolean
+ description: Whether the delete operation was successful
+
+ SetResponse:
+ description: Represents a response for a set operation
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Status code of the response
+ enum:
+ - 0
+ set:
+ type: boolean
+ description: Whether the set operation was successful
+
parameters:
metalake:
name: metalake
@@ -311,6 +396,29 @@ components:
schema:
type: string
+ user:
+ name: user
+ in: path
+ description: The name of the user
+ required: true
+ schema:
+ type: string
+
+ group:
+ name: group
+ in: path
+ description: The name of the group
+ required: true
+ schema:
+ type: string
+ role:
+ name: role
+ in: path
+ description: The name of the role
+ required: true
+ schema:
+ type: string
+
metadataObjectType:
name: metadataObjectType
in: path
@@ -324,6 +432,8 @@ components:
- "table"
- "fileset"
- "topic"
+ - "role"
+ - "metalake"
metadataObjectFullName:
name: metadataObjectFullName
diff --git a/docs/open-api/owners.yaml b/docs/open-api/owners.yaml
new file mode 100644
index 000000000..51ca06ccd
--- /dev/null
+++ b/docs/open-api/owners.yaml
@@ -0,0 +1,176 @@
+#
+# 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.
+#
+
+---
+
+paths:
+
+ /metalakes/{metalake}/owners/{metadataObjectType}/{metadataObjectFullName}:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+ - $ref: "./openapi.yaml#/components/parameters/metadataObjectType"
+ - $ref: "./openapi.yaml#/components/parameters/metadataObjectFullName"
+
+ put:
+ tags:
+ - access control
+ summary: Set owner
+ operationId: setOwner
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/OwnerSetRequest"
+ examples:
+ OwnerSetRequest:
+ $ref: "#/components/examples/OwnerSetRequest"
+
+ responses:
+ "200":
+ description: Returns the set operation result
+ $ref: "./openapi.yaml#/components/responses/SetResponse"
+
+ "404":
+ description: Not Found - The specified owner or metadata object does
not exist in the specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ NotFoundException:
+ $ref: "#/components/examples/NotFoundException"
+
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+ get:
+ tags:
+ - access control
+ summary: Get owner
+ operationId: getOwner
+ description: Returns the specified owner information in the specified
metalake
+ responses:
+ "200":
+ description: Returns the owner object
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "#/components/responses/OwnerResponse"
+ examples:
+ OwnerResponse:
+ $ref: "#/components/examples/OwnerResponse"
+ "404":
+ description: Not Found - The specified owner does not exist in the
specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ NoSuchMetadataObjectException:
+ $ref: "#/components/examples/NoSuchMetadataObjectException"
+
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+
+components:
+
+ schemas:
+ Owner:
+ type: object
+ required:
+ - name
+ - type
+ properties:
+ name:
+ type: string
+ description: The name of the owner
+ type:
+ type: string
+ enum:
+ - USER
+ - GROUP
+ description: The type of the owner
+
+ OwnerSetRequest:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ description: The name of the owner
+ type:
+ type: string
+ enum:
+ - USER
+ - GROUP
+ description: The type of the owner
+
+ responses:
+ OwnerResponse:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Status code of the response
+ enum:
+ - 0
+ owner:
+ $ref: "#/components/schemas/Owner"
+
+ examples:
+ OwnerSetRequest:
+ value: {
+ "name": "user1",
+ "type": "USER"
+ }
+
+ OwnerResponse:
+ value: {
+ "code": 0,
+ "owner": {
+ "name": "user1",
+ "type": "USER",
+ }
+ }
+
+
+ NoSuchMetadataObjectException:
+ value: {
+ "code": 1003,
+ "type": "NoSuchMetadataObjectException",
+ "message": "Metadata object does not exist",
+ "stack": [
+ "org.apache.gravitino.exceptions.NoSuchUserException: Metadata
object does not exist",
+ "..."
+ ]
+ }
+
+ NotFoundException:
+ value: {
+ "code": 1003,
+ "type": "NotFoundException",
+ "message": "Metadata object or owner does not exist",
+ "stack": [
+ "org.apache.gravitino.exceptions.NotFoundException: Metadata object
or owner does not exist",
+ "..."
+ ]
+ }
\ No newline at end of file
diff --git a/docs/open-api/permissions.yaml b/docs/open-api/permissions.yaml
new file mode 100644
index 000000000..0b5bbddd7
--- /dev/null
+++ b/docs/open-api/permissions.yaml
@@ -0,0 +1,262 @@
+#
+# 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.
+#
+
+---
+
+paths:
+
+ /metalakes/{metalake}/permissions/users/{user}/grant:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+ - $ref: "./openapi.yaml#/components/parameters/user"
+
+ put:
+ tags:
+ - access control
+ summary: Grant roles to a user
+ operationId: grantRoleToUser
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/RoleGrantRequest"
+ examples:
+ RoleGrantRequest:
+ $ref: "#/components/examples/RoleGrantRequest"
+
+ responses:
+ "200":
+ description: Returns the granted user object
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./users.yaml#/components/responses/UserResponse"
+ examples:
+ UserResponse:
+ $ref: "./users.yaml#/components/examples/UserResponse"
+
+ "404":
+ description: Not Found - The specified user or role does not exist
in the specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ NoSuchMetalakeException:
+ $ref:
"./metalakes.yaml#/components/examples/NoSuchMetalakeException"
+ NoSuchUserException:
+ $ref: "./users.yaml#/components/examples/NoSuchUserException"
+ NoSuchRoleException:
+ $ref: "./roles.yaml#/components/examples/NoSuchRoleException"
+
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+ /metalakes/{metalake}/permissions/users/{user}/revoke:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+ - $ref: "./openapi.yaml#/components/parameters/user"
+
+ put:
+ tags:
+ - access control
+ summary: Revoke roles to a user
+ operationId: revokeRoleFromUser
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/RoleRevokeRequest"
+ examples:
+ RoleRevokeRequest:
+ $ref: "#/components/examples/RoleRevokeRequest"
+
+ responses:
+ "200":
+ description: Returns the revoked user object
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./users.yaml#/components/responses/UserResponse"
+ examples:
+ UserResponse:
+ $ref: "./users.yaml#/components/examples/UserResponse"
+
+ "404":
+ description: Not Found - The specified user or role does not exist
in the specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ NoSuchMetalakeException:
+ $ref:
"./metalakes.yaml#/components/examples/NoSuchMetalakeException"
+ NoSuchUserException:
+ $ref: "./users.yaml#/components/examples/NoSuchUserException"
+ NoSuchRoleException:
+ $ref: "./roles.yaml#/components/examples/NoSuchRoleException"
+
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+ /metalakes/{metalake}/permissions/groups/{group}/grant:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+ - $ref: "./openapi.yaml#/components/parameters/group"
+
+ put:
+ tags:
+ - access control
+ summary: Grant roles to a group
+ operationId: grantRoleToGroup
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/RoleGrantRequest"
+ examples:
+ RoleGrantRequest:
+ $ref: "#/components/examples/RoleGrantRequest"
+
+ responses:
+ "200":
+ description: Returns the granted group object
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./groups.yaml#/components/responses/GroupResponse"
+ examples:
+ GroupResponse:
+ $ref: "./groups.yaml#/components/examples/GroupResponse"
+
+ "404":
+ description: Not Found - The specified group or role does not exist
in the specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ NoSuchMetalakeException:
+ $ref:
"./metalakes.yaml#/components/examples/NoSuchMetalakeException"
+ NoSuchGroupException:
+ $ref:
"./groups.yaml#/components/examples/NoSuchGroupException"
+ NoSuchRoleException:
+ $ref: "./roles.yaml#/components/examples/NoSuchRoleException"
+
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+ /metalakes/{metalake}/permissions/groups/{group}/revoke:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+ - $ref: "./openapi.yaml#/components/parameters/group"
+
+ put:
+ tags:
+ - access control
+ summary: Revoke roles to a group
+ operationId: revokeRoleFromGroup
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/RoleRevokeRequest"
+ examples:
+ RoleRevokeRequest:
+ $ref: "#/components/examples/RoleRevokeRequest"
+
+ responses:
+ "200":
+ description: Returns the revoked group object
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./groups.yaml#/components/responses/GroupResponse"
+ examples:
+ GroupResponse:
+ $ref: "./groups.yaml#/components/examples/GroupResponse"
+
+ "404":
+ description: Not Found - The specified group or role does not exist
in the specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ NoSuchMetalakeException:
+ $ref:
"./metalakes.yaml#/components/examples/NoSuchMetalakeException"
+ NoSuchGroupException:
+ $ref:
"./groups.yaml#/components/examples/NoSuchGroupException"
+ NoSuchRoleException:
+ $ref: "./roles.yaml#/components/examples/NoSuchRoleException"
+
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+components:
+
+ schemas:
+ User:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ description: The name of the user
+ roles:
+ type: array
+ items:
+ type: string
+ description: The roles of the user
+
+ RoleGrantRequest:
+ type: object
+ required:
+ - roleNames
+ properties:
+ roleNames:
+ type: array
+ description: The role names need to grant
+ items:
+ type: string
+
+ RoleRevokeRequest:
+ type: object
+ required:
+ - roleNames
+ properties:
+ roleNames:
+ type: array
+ description: The role names need to revoke
+ items:
+ type: string
+
+
+ examples:
+
+ RoleGrantRequest:
+ value: {
+ "roleNames": ["role1"],
+ }
+
+ RoleRevokeRequest:
+ value: {
+ "roleNames": [ "role1" ],
+ }
\ No newline at end of file
diff --git a/docs/open-api/roles.yaml b/docs/open-api/roles.yaml
new file mode 100644
index 000000000..005cd89e3
--- /dev/null
+++ b/docs/open-api/roles.yaml
@@ -0,0 +1,311 @@
+#
+# 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.
+#
+
+---
+
+paths:
+
+ /metalakes/{metalake}/roles:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+
+ post:
+ tags:
+ - access control
+ summary: Create role
+ operationId: createRole
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/RoleCreateRequest"
+ examples:
+ RoleCreateRequest:
+ $ref: "#/components/examples/RoleCreateRequest"
+
+ responses:
+ "200":
+ description: Returns the created role object
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "#/components/responses/RoleResponse"
+ examples:
+ RoleResponse:
+ $ref: "#/components/examples/RoleResponse"
+
+ "404":
+ description: Not Found - The specified securable object does not
exist in the specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ NoSuchMetadataObjectException:
+ $ref: "#/components/examples/NoSuchMetadataObjectException"
+
+ "409":
+ description: Conflict - The target role already exists in the
specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ RoleAlreadyExistsException:
+ $ref: "#/components/examples/RoleAlreadyExistsException"
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+ /metalakes/{metalake}/roles/{role}:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+ - $ref: "./openapi.yaml#/components/parameters/role"
+
+ get:
+ tags:
+ - access control
+ summary: Get Role
+ operationId: getRole
+ description: Returns the specified role information in the specified
metalake
+ responses:
+ "200":
+ description: Returns the role object
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "#/components/responses/RoleResponse"
+ examples:
+ RoleResponse:
+ $ref: "#/components/examples/RoleResponse"
+ "404":
+ description: Not Found - The specified role does not exist in the
specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ NoSuchMetalakeException:
+ $ref:
"./metalakes.yaml#/components/examples/NoSuchMetalakeException"
+ NoSuchRoleException:
+ $ref: "#/components/examples/NoSuchRoleException"
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+ delete:
+ tags:
+ - access control
+ summary: Delete role
+ operationId: deleteRole
+ responses:
+ "200":
+ $ref: "./openapi.yaml#/components/responses/DeleteResponse"
+ "400":
+ $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+components:
+
+ schemas:
+
+ Privilege:
+ type: object
+ required:
+ - name
+ - condition
+ properties:
+ name:
+ type: string
+ enum:
+ - CREATE_CATALOG
+ - USE_CATALOG
+ - CREATE_SCHEMA
+ - USE_SCHEMA
+ - CREATE_TABLE
+ - MODIFY_TABLE
+ - SELECT_TABLE
+ - CREATE_FILESET
+ - WRITE_FILESET
+ - READ_FILESET
+ - CREATE_TOPIC
+ - PRODUCE_TOPIC
+ - CONSUME_TOPIC
+ - MANAGE_USERS
+ - MANAGE_GROUPS
+ - CREATE_ROLE
+ - MANAGE_GRANTS
+ description: The name of the privilege
+ condition:
+ type: string
+ enum:
+ - ALLOW
+ - DENY
+ description: The condition of the privilege, `ALLOW` or `DENY`
+
+ SecurableObject:
+ type: object
+ required:
+ - fullName
+ - type
+ properties:
+ fullName:
+ type: string
+ description: The full name of the securable object
+ type:
+ type: string
+ enum:
+ - "CATALOG"
+ - "SCHEMA"
+ - "TABLE"
+ - "FILESET"
+ - "TOPIC"
+ - "METALAKE"
+ description: The type of the securable object
+ privileges:
+ type: array
+ description: A list of privileges
+ items:
+ $ref: "#/components/schemas/Privilege"
+
+ Role:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ description: The name of the role
+ properties:
+ type: object
+ description: A map of properties for the role
+ nullable: true
+ default: { }
+ additionalProperties:
+ type: string
+ securableObjects:
+ type: array
+ description: A list of securable objects
+ items:
+ $ref: "#/components/schemas/SecurableObject"
+
+ RoleCreateRequest:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ description: The name of the role
+ properties:
+ type: object
+ description: A map of properties for the role
+ nullable: true
+ default: { }
+ additionalProperties:
+ type: string
+ securableObjects:
+ type: array
+ description: A list of securable objects
+ items:
+ $ref: "#/components/schemas/SecurableObject"
+
+ responses:
+ RoleResponse:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Status code of the response
+ enum:
+ - 0
+ role:
+ $ref: "#/components/schemas/Role"
+
+ examples:
+ RoleCreateRequest:
+ value: {
+ "name": "role1",
+ "properties": {"k1": "v1"},
+ "securableObjects": [
+ {
+ "fullName" : "catalog1.schema1.table1",
+ "type": "TABLE",
+ "privileges": [
+ {
+ "name": "SELECT_TABLE",
+ "condition": "ALLOW"
+ }
+ ]
+ }
+ ]
+ }
+
+ RoleResponse:
+ value: {
+ "code": 0,
+ "role": {
+ "name": "role1",
+ "properties" : { "k1": "v1" },
+ "securableObjects": [
+ {
+ "fullName": "catalog1.schema1.table1",
+ "type": "TABLE",
+ "privileges": [
+ {
+ name: "SELECT_TABLE",
+ condition: "ALLOW"
+ }
+ ]
+ }
+ ]
+ }
+ }
+
+ RoleAlreadyExistsException:
+ value: {
+ "code": 1004,
+ "type": "RoleAlreadyExistsException",
+ "message": "Role already exists",
+ "stack": [
+ "org.apache.gravitino.exceptions.RoleAlreadyExistsException: Role
already exists: role1"
+ ]
+ }
+
+ NoSuchRoleException:
+ value: {
+ "code": 1003,
+ "type": "NoSuchRoleException",
+ "message": "Role does not exist",
+ "stack": [
+ "org.apache.gravitino.exceptions.NoSuchRoleException: Role does not
exist",
+ "..."
+ ]
+ }
+
+ NoSuchMetadataObjectException:
+ value: {
+ "code": 1003,
+ "type": "NoSuchMetadataObjectException",
+ "message": "Metadata object does not exist",
+ "stack": [
+ "org.apache.gravitino.exceptions.NoSuchUserException: Metadata
object does not exist",
+ "..."
+ ]
+ }
\ No newline at end of file
diff --git a/docs/open-api/users.yaml b/docs/open-api/users.yaml
new file mode 100644
index 000000000..d83c27a46
--- /dev/null
+++ b/docs/open-api/users.yaml
@@ -0,0 +1,191 @@
+#
+# 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.
+#
+
+---
+
+paths:
+
+ /metalakes/{metalake}/users:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+
+ post:
+ tags:
+ - access control
+ summary: Add user
+ operationId: addUser
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: "#/components/schemas/UserAddRequest"
+ examples:
+ UserAddRequest:
+ $ref: "#/components/examples/UserAddRequest"
+
+ responses:
+ "200":
+ description: Returns the added user object
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "#/components/responses/UserResponse"
+ examples:
+ UserResponse:
+ $ref: "#/components/examples/UserResponse"
+ "409":
+ description: Conflict - The target user already exists in the
specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ UserAlreadyExistsException:
+ $ref: "#/components/examples/UserAlreadyExistsException"
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+ /metalakes/{metalake}/users/{user}:
+ parameters:
+ - $ref: "./openapi.yaml#/components/parameters/metalake"
+ - $ref: "./openapi.yaml#/components/parameters/user"
+
+ get:
+ tags:
+ - access control
+ summary: Get user
+ operationId: getUser
+ description: Returns the specified user information in the specified
metalake
+ responses:
+ "200":
+ description: Returns the user object
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "#/components/responses/UserResponse"
+ examples:
+ UserResponse:
+ $ref: "#/components/examples/UserResponse"
+ "404":
+ description: Not Found - The specified user does not exist in the
specified metalake
+ content:
+ application/vnd.gravitino.v1+json:
+ schema:
+ $ref: "./openapi.yaml#/components/schemas/ErrorModel"
+ examples:
+ NoSuchMetalakeException:
+ $ref:
"./metalakes.yaml#/components/examples/NoSuchMetalakeException"
+ NoSuchUserException:
+ $ref: "#/components/examples/NoSuchUserException"
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+ delete:
+ tags:
+ - access control
+ summary: Remove user
+ operationId: removeUser
+ responses:
+ "200":
+ $ref: "./openapi.yaml#/components/responses/RemoveResponse"
+ "400":
+ $ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
+ "5xx":
+ $ref: "./openapi.yaml#/components/responses/ServerErrorResponse"
+
+components:
+
+ schemas:
+ User:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ description: The name of the user
+ roles:
+ type: array
+ items:
+ type: string
+ description: The roles of the user
+ audit:
+ $ref: "./openapi.yaml#/components/schemas/Audit"
+
+ UserAddRequest:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ description: The name of the user
+
+ responses:
+ UserResponse:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Status code of the response
+ enum:
+ - 0
+ user:
+ $ref: "#/components/schemas/User"
+
+ examples:
+ UserAddRequest:
+ value: {
+ "name": "user1",
+ }
+
+ UserResponse:
+ value: {
+ "code": 0,
+ "user": {
+ "name": "user1",
+ "roles": [],
+ "audit": {
+ "creator": "gravitino",
+ "createTime": "2023-12-08T06:41:25.595Z"
+ },
+ }
+ }
+
+ UserAlreadyExistsException:
+ value: {
+ "code": 1004,
+ "type": "UserAlreadyExistsException",
+ "message": "User already exists",
+ "stack": [
+ "org.apache.gravitino.exceptions.UserAlreadyExistsException: User
already exists: user1"
+ ]
+ }
+
+ NoSuchUserException:
+ value: {
+ "code": 1003,
+ "type": "NoSuchUserException",
+ "message": "User does not exist",
+ "stack": [
+ "org.apache.gravitino.exceptions.NoSuchUserException: User does not
exist",
+ "..."
+ ]
+ }
\ No newline at end of file
