Skip to content

Commit

Permalink
[#2367] improvement(fileset): Add open API doc for fileset catalog (#…
Browse files Browse the repository at this point in the history 
…2403)

<!--
1. Title: [#<issue>] <type>(<scope>): <subject>
   Examples:
     - "[#123] feat(operator): support xxx"
     - "[#233] fix: check null before access result in xxx"
     - "[MINOR] refactor: fix typo in variable name"
     - "[MINOR] docs: fix typo in README"
     - "[#255] test: fix flaky test NameOfTheTest"
   Reference: https://www.conventionalcommits.org/en/v1.0.0/
2. If the PR is unfinished, please mark this PR as draft.
-->

### What changes were proposed in this pull request?

- close #2367 

### Why are the changes needed?


- Fix: #2367 

### Does this PR introduce _any_ user-facing change?

- no

### How was this patch tested?

- `./gradlew build`

---------

Co-authored-by: mchades <liminghuang@datastrato.com>
  • Loading branch information
@coolderli @mchades
coolderli and mchades authored Mar 1, 2024
1 parent 1defc87 commit 580b622
Show file tree
Hide file tree
Showing 2 changed files with 407 additions and 0 deletions.
393 changes: 393 additions & 0 deletions docs/open-api/filesets.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,393 @@
#
# Copyright 2024 Datastrato Pvt Ltd.
# This software is licensed under the Apache License version 2.
#

---

paths:

/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/filesets:
parameters:
- $ref: "./openapi.yaml#/components/parameters/metalake"
- $ref: "./openapi.yaml#/components/parameters/catalog"
- $ref: "./openapi.yaml#/components/parameters/schema"

get:
tags:
- fileset
summary: List filesets
operationId: listFilesets
responses:
"200":
$ref: "./openapi.yaml#/components/responses/EntityListResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
"5xx":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

post:
tags:
- fileset
summary: Create fileset
operationId: createFileset
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/FilesetCreateRequest"
examples:
FilesetCreateRequest:
$ref: "#/components/examples/FilesetCreateRequest"
responses:
"200":
$ref: "#/components/responses/FilesetResponse"
"409":
description: Conflict - The target fileset already exists
content:
application/vnd.gravitino.v1+json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
FilesetAlreadyExistsErrorResponse:
$ref: "#/components/examples/FilesetAlreadyExistsException"
"5xx":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


/metalakes/{metalake}/catalogs/{catalog}/schemas/{schema}/filesets/{fileset}:
parameters:
- $ref: "./openapi.yaml#/components/parameters/metalake"
- $ref: "./openapi.yaml#/components/parameters/catalog"
- $ref: "./openapi.yaml#/components/parameters/schema"
- $ref: "./openapi.yaml#/components/parameters/fileset"

get:
tags:
- fileset
summary: Get fileset
operationId: loadFileset
description: Returns the specified fileset object
responses:
"200":
$ref: "#/components/responses/FilesetResponse"
"404":
description: Not Found - The target fileset does not exist
content:
application/vnd.gravitino.v1+json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
NoSuchMetalakeException:
$ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
NoSuchCatalogException:
$ref: "./catalogs.yaml#/components/examples/NoSuchCatalogException"
NoSuchSchemaException:
$ref: "./schemas.yaml#/components/examples/NoSuchSchemaException"
NoSuchFilesetException:
$ref: "#/components/examples/NoSuchFilesetException"
"5xx":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

put:
tags:
- fileset
summary: Update fileset
operationId: alterFileset
description: Updates the specified fileset in a schema
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/FilesetUpdatesRequest"
responses:
"200":
$ref: "#/components/responses/FilesetResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
"404":
description: Not Found - The target fileset does not exist
content:
application/vnd.gravitino.v1+json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
NoSuchMetalakeException:
$ref: "./metalakes.yaml#/components/examples/NoSuchMetalakeException"
NoSuchCatalogException:
$ref: "./catalogs.yaml#/components/examples/NoSuchCatalogException"
NoSuchSchemaException:
$ref: "./schemas.yaml#/components/examples/NoSuchSchemaException"
NoSuchFilesetException:
$ref: "#/components/examples/NoSuchFilesetException"
"409":
description: Conflict - The target fileset already exists
content:
application/vnd.gravitino.v1+json:
schema:
$ref: "./openapi.yaml#/components/schemas/ErrorModel"
examples:
FilesetAlreadyExistsErrorResponse:
$ref: "#/components/examples/FilesetAlreadyExistsException"
"5xx":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"

delete:
tags:
- fileset
summary: Drop fileset
operationId: dropFileset
responses:
"200":
$ref: "./openapi.yaml#/components/responses/DropResponse"
"400":
$ref: "./openapi.yaml#/components/responses/BadRequestErrorResponse"
"5xx":
$ref: "./openapi.yaml#/components/responses/ServerErrorResponse"


components:

schemas:
Fileset:
type: object
required:
- name
properties:
name:
type: string
description: The name of the fileset
description:
type: string
description: The description of the fileset
nullable: true
type:
type: string
description: The type of the fileset
nullable: true
comment:
type: string
description: The comment of the fileset
nullable: true
storageLocation:
type: string
description: The location of the fileset
nullable: true
properties:
type: object
description: The properties of the fileset
nullable: true
default: {}
additionalProperties:
type: string
FilesetCreateRequest:
type: object
required:
- name
properties:
name:
type: string
description: The name of the fileset
description:
type: string
description: The description of the fileset
nullable: true
type:
type: string
description: The type of the fileset
nullable: true
comment:
type: string
description: The comment of the fileset
nullable: true
storageLocation:
type: string
description: The location of the fileset
nullable: true
properties:
type: object
description: The properties of the fileset
nullable: true
default: {}
additionalProperties:
type: string

FilesetUpdatesRequest:
type: object
required:
- name
properties:
updates:
type: array
items:
$ref: "#/components/schemas/FilesetUpdateRequest"

FilesetUpdateRequest:
oneOf:
- $ref: "#/components/schemas/RenameFilesetRequest"
- $ref: "#/components/schemas/SetFilesetPropertiesRequest"
- $ref: "#/components/schemas/UpdateFilesetCommentRequest"
- $ref: "#/components/schemas/RemoveFilesetPropertiesRequest"
discriminator:
propertyName: "@type"
mapping:
rename: "#/components/schemas/RenameFilesetRequest"
setProperties: "#/components/schemas/SetFilesetPropertiesRequest"
updateComment: "#/components/schemas/UpdateFilesetCommentRequest"
removeProperties: "#/components/schemas/RemoveFilesetPropertiesRequest"

RenameFilesetRequest:
type: object
required:
- "@type"
- newName
properties:
"@type":
type: string
description: The type of the update
enum:
- rename
newName:
type: string
description: The new name of the fileset
example: {
"@type": "rename",
"newName": "newName"
}

SetFilesetPropertiesRequest:
type: object
required:
- "@type"
- property
- value
properties:
"@type":
type: string
description: The type of the update
enum:
- setProperty
property:
type: string
description: The name of the property to set
value:
type: string
description: The value of the property to set
example: {
"@type": "setProperty",
"property": "key",
"value": "value"
}

UpdateFilesetCommentRequest:
type: object
required:
- "@type"
- newComment
properties:
"@type":
type: string
description: The type of the update
enum:
- updateComment
newComment:
type: string
description: The new comment of the fileset
example: {
"@type": "updateComment",
"newComment": "new comment"
}

RemoveFilesetPropertiesRequest:
type: object
required:
- "@type"
- property
properties:
"@type":
type: string
description: The type of the update
enum:
- removeProperty
property:
type: string
description: The property to remove
example: {
"@type": "removeProperty",
"property": "key1"
}

responses:
FilesetResponse:
description: The response of fileset object
content:
application/vnd.gravitino.v1+json:
schema:
type: object
properties:
code:
type: integer
format: int32
description: Status code of the response
enum:
- 0
fileset:
$ref: "#/components/schemas/Fileset"
examples:
FilesetResponse:
$ref: "#/components/examples/FilesetResponse"


examples:
FilesetCreateRequest:
value: {
"name": "fileset1",
"description": "This is a fileset",
"type": "managed",
"comment": "This is a comment",
"storageLocation": "s3://bucket/path",
"properties": {
"key1": "value1",
"key2": "value2"
}
}

FilesetResponse:
value: {
"code": 0,
"fileset" : {
"name": "fileset1",
"description": "This is a fileset",
"type": "managed",
"comment": "This is a comment",
"storageLocation": "s3://bucket/path",
"properties": {
"key1": "value1",
"key2": "value2"
}
}
}

FilesetAlreadyExistsException:
value: {
"code": 1001,
"type": "FilesetAlreadyExistsException",
"message": "Fileset already exists",
"stack": [
"java.lang.FilesetAlreadyExistsException: Fileset already exists"
]
}

NoSuchFilesetException:
value: {
"code": 1004,
"type": "NoSuchFilesetException",
"message": "Fileset does not exist",
"stack": [
"java.lang.NoSuchFilesetException: Fileset does not exist"
]
}




Loading

0 comments on commit 580b622

Please sign in to comment.