diff --git a/docs/open-api/groups.yaml b/docs/open-api/groups.yaml new file mode 100644 index 00000000000..f21226b100f --- /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 16eb47ff955..edac71ec683 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 00000000000..51ca06ccdd6 --- /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 00000000000..0b5bbddd7e7 --- /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 00000000000..005cd89e3cb --- /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 00000000000..d83c27a4663 --- /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