From f88e18c23e7ebd3c879eacbd2e4e0d77fe251fe5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Vall=C3=A9s?= Date: Tue, 30 Jan 2024 13:48:10 +0100 Subject: [PATCH 1/3] fix: align documentation of new endpoints The format specification in the previously documented endpoints uses brackets for placeholders and is surrounded by ticks (`). --- vdp/pipeline/v1beta/common.proto | 18 +++++++------- vdp/pipeline/v1beta/pipeline.proto | 24 ++++++++++++------- .../v1beta/pipeline_public_service.proto | 13 +++++----- 3 files changed, 30 insertions(+), 25 deletions(-) diff --git a/vdp/pipeline/v1beta/common.proto b/vdp/pipeline/v1beta/common.proto index 4422bc4d..c4a7214c 100644 --- a/vdp/pipeline/v1beta/common.proto +++ b/vdp/pipeline/v1beta/common.proto @@ -66,18 +66,18 @@ message Permission { // CheckNameRequest represents a request to verify if a name is // available. message CheckNameRequest { - // The name of the resource to be checked, should be in the formats: - // - users//pipelines/ - // - users//connectors/ - // - organizations//pipelines/ - // - organizations//connectors/ + // The name of the resource to be checked. For the moment, only pipeline and + // connector names can be checked. The following formats are accepted: + // - `users/{user.id}/pipelines/{pipeline.id}` + // - `users/{user.id}/connectors/{connector.id}` + // - `organizations/{organization.id}/pipelines/{pipeline.id}` + // - `organizations/{organization.id}/connectors/{connector.id}` string name = 1 [(google.api.field_behavior) = REQUIRED]; } -// CheckNameResponse contains the availability of a name -// of resource that's using it. +// CheckNameResponse contains the availability of a resource name. message CheckNameResponse { - // Availability of Name + // Name defines the availability of a resource name. enum Name { // Unspecified. NAME_UNSPECIFIED = 0; @@ -87,6 +87,6 @@ message CheckNameResponse { NAME_UNAVAILABLE = 2; } - // Availability + // The availability of the requested name. Name availability = 1; } diff --git a/vdp/pipeline/v1beta/pipeline.proto b/vdp/pipeline/v1beta/pipeline.proto index 018ebb64..c6d9a940 100644 --- a/vdp/pipeline/v1beta/pipeline.proto +++ b/vdp/pipeline/v1beta/pipeline.proto @@ -478,7 +478,8 @@ message RenameUserPipelineResponse { Pipeline pipeline = 1; } -// CloneUserPipelineRequest represents a request to clone a pipeline owned by a user. +// CloneUserPipelineRequest represents a request to clone a pipeline owned by a +// user. message CloneUserPipelineRequest { // The resource name of the pipeline, which allows its access by parent user // and ID. @@ -490,8 +491,10 @@ message CloneUserPipelineRequest { field_configuration: {path_param_name: "user_pipeline_name"} } ]; - // The target pipeline - // - Format: `users/{user.id}/pipelines/{pipeline.id}` or `organizations/{org.id}/pipelines/{pipeline.id}` + // The target pipeline name. It can be under a user or an organization + // namespace, so the following formats are accepted: + // - `users/{user.id}/pipelines/{pipeline.id}` + // - `organizations/{organization.id}/pipelines/{pipeline.id}` string target = 2 [(google.api.field_behavior) = REQUIRED]; } @@ -956,11 +959,12 @@ message RenameOrganizationPipelineResponse { Pipeline pipeline = 1; } -// CloneOrganizationPipelineRequest represents a request to clone a pipeline owned by a organization. +// CloneOrganizationPipelineRequest represents a request to clone a pipeline +// owned by an organization. message CloneOrganizationPipelineRequest { - // The resource name of the pipeline, which allows its access by parent user - // and ID. - // - Format: `organizations/{org.id}/pipelines/{pipeline.id}`. + // The resource name of the pipeline, which allows its access by parent + // organization and ID. + // - Format: `organizations/{organization.id}/pipelines/{pipeline.id}`. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = {type: "api.instill.tech/Pipeline"}, @@ -968,8 +972,10 @@ message CloneOrganizationPipelineRequest { field_configuration: {path_param_name: "user_pipeline_name"} } ]; - // The target pipeline - // - Format: `users/{user.id}/pipelines/{pipeline.id}` or `organizations/{org.id}/pipelines/{pipeline.id}` + // The target pipeline name. It can be under a user or an organization + // namespace, so the following formats are accepted: + // - `users/{user.id}/pipelines/{pipeline.id}` + // - `organizations/{organization.id}/pipelines/{pipeline.id}` string target = 2 [(google.api.field_behavior) = REQUIRED]; } diff --git a/vdp/pipeline/v1beta/pipeline_public_service.proto b/vdp/pipeline/v1beta/pipeline_public_service.proto index 4f12ebd4..7c73da6e 100644 --- a/vdp/pipeline/v1beta/pipeline_public_service.proto +++ b/vdp/pipeline/v1beta/pipeline_public_service.proto @@ -152,7 +152,8 @@ service PipelinePublicService { // Clone a pipeline owned by a user // - // Clone a pipeline owned by a user, the target pipeline can be under a user or organization namespace. + // Clones a pipeline owned by a user. The new pipeline may have a different + // parent, and this can be either a user or an organization. rpc CloneUserPipeline(CloneUserPipelineRequest) returns (CloneUserPipelineResponse) { option (google.api.http) = { post: "/v1beta/{name=users/*/pipelines/*}/clone" @@ -422,7 +423,8 @@ service PipelinePublicService { // Clone a pipeline owned by an organization // - // Clone a pipeline owned by an organization, the target pipeline can be under a user or organization namespace. + // Clones a pipeline owned by an organization. The new pipeline may have a + // different parent, and this can be either a user or an organization. rpc CloneOrganizationPipeline(CloneOrganizationPipelineRequest) returns (CloneOrganizationPipelineResponse) { option (google.api.http) = { post: "/v1beta/{name=organizations/*/pipelines/*}/clone" @@ -896,11 +898,8 @@ service PipelinePublicService { // Check the availibity of a resource name // - // Check the availibity of a resource name. The name should be in the formats: - // - users//pipelines/ - // - users//connectors/ - // - organizations//pipelines/ - // - organizations//connectors/ + // Check whether a resource name is already in use. Currently this endpoint + // only supports pipeline and connector resource names. rpc CheckName(CheckNameRequest) returns (CheckNameResponse) { option (google.api.http) = { post: "/v1beta/check-name" From 4e379a8e42c8542800bad663e6d0ba19f97e8de2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Vall=C3=A9s?= Date: Tue, 30 Jan 2024 13:49:35 +0100 Subject: [PATCH 2/3] fix: s/a organization/an organization/ --- model/model/v1alpha/model_public_service.proto | 2 +- vdp/pipeline/v1beta/connector.proto | 4 ++-- vdp/pipeline/v1beta/pipeline.proto | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/model/model/v1alpha/model_public_service.proto b/model/model/v1alpha/model_public_service.proto index 2e39f694..cea0d552 100644 --- a/model/model/v1alpha/model_public_service.proto +++ b/model/model/v1alpha/model_public_service.proto @@ -262,7 +262,7 @@ service ModelPublicService { // Create a new model // - // Creates a new model under the parenthood of a organization. This is an + // Creates a new model under the parenthood of an organization. This is an // asynchronous endpoint, i.e., the server will not wait for the model to be // created in order to respond. Instead, it will return a response with the // necessary information to access the result and status of the creation diff --git a/vdp/pipeline/v1beta/connector.proto b/vdp/pipeline/v1beta/connector.proto index 2519f66f..d0260003 100644 --- a/vdp/pipeline/v1beta/connector.proto +++ b/vdp/pipeline/v1beta/connector.proto @@ -437,7 +437,7 @@ message CreateOrganizationConnectorResponse { } // ListOrganizationConnectorsRequest represents a request to list the -// connectors of a organization. +// connectors of an organization. message ListOrganizationConnectorsRequest { // The maximum number of connectors to return. If this parameter is // unspecified, at most 10 connectors will be returned. The cap value for this @@ -644,7 +644,7 @@ message TestOrganizationConnectorResponse { } // WatchOrganizationConnectorRequest represents a request to fetch the state of -// a organization-owned connector. +// an organization-owned connector. message WatchOrganizationConnectorRequest { // The resource name of the connector, which allows its access by parent // connector and ID. diff --git a/vdp/pipeline/v1beta/pipeline.proto b/vdp/pipeline/v1beta/pipeline.proto index c6d9a940..9710a9fe 100644 --- a/vdp/pipeline/v1beta/pipeline.proto +++ b/vdp/pipeline/v1beta/pipeline.proto @@ -814,7 +814,7 @@ message CreateOrganizationPipelineResponse { } // ListOrganizationPipelinesRequest represents a request to list the pipelines -// of a organization. +// of an organization. message ListOrganizationPipelinesRequest { // The maximum number of pipelines to return. If this parameter is // unspecified, at most 10 pipelines will be returned. The cap value for this @@ -1207,7 +1207,7 @@ message RenameOrganizationPipelineReleaseResponse { } // WatchOrganizationPipelineReleaseRequest represents a request to query the -// state of a organization-owned pipeline release. +// state of an organization-owned pipeline release. message WatchOrganizationPipelineReleaseRequest { // The resource name of the pipeline release, which allows its access by // parent pipeline and ID. From cba441e03bfa4bd34f2072ed67db999082dde51d Mon Sep 17 00:00:00 2001 From: droplet-bot Date: Tue, 30 Jan 2024 12:50:29 +0000 Subject: [PATCH 3/3] chore: auto-gen by protobufs triggered by commit: https://github.com/instill-ai/protobufs/commit/f2843d445e4e0f2d09703f6c94529fa9f9fec427 --- openapiv2/model/service.swagger.yaml | 2 +- openapiv2/vdp/service.swagger.yaml | 63 ++++++++++++++++------------ 2 files changed, 37 insertions(+), 28 deletions(-) diff --git a/openapiv2/model/service.swagger.yaml b/openapiv2/model/service.swagger.yaml index eca84409..aa273c91 100644 --- a/openapiv2/model/service.swagger.yaml +++ b/openapiv2/model/service.swagger.yaml @@ -826,7 +826,7 @@ paths: post: summary: Create a new model description: |- - Creates a new model under the parenthood of a organization. This is an + Creates a new model under the parenthood of an organization. This is an asynchronous endpoint, i.e., the server will not wait for the model to be created in order to respond. Instead, it will return a response with the necessary information to access the result and status of the creation diff --git a/openapiv2/vdp/service.swagger.yaml b/openapiv2/vdp/service.swagger.yaml index 523e51d8..9453778c 100644 --- a/openapiv2/vdp/service.swagger.yaml +++ b/openapiv2/vdp/service.swagger.yaml @@ -535,7 +535,9 @@ paths: /v1beta/{user_pipeline_name}/clone: post: summary: Clone a pipeline owned by a user - description: Clone a pipeline owned by a user, the target pipeline can be under a user or organization namespace. + description: |- + Clones a pipeline owned by a user. The new pipeline may have a different + parent, and this can be either a user or an organization. operationId: PipelinePublicService_CloneUserPipeline responses: "200": @@ -1508,7 +1510,9 @@ paths: /v1beta/{user_pipeline_name_1}/clone: post: summary: Clone a pipeline owned by an organization - description: Clone a pipeline owned by an organization, the target pipeline can be under a user or organization namespace. + description: |- + Clones a pipeline owned by an organization. The new pipeline may have a + different parent, and this can be either a user or an organization. operationId: PipelinePublicService_CloneOrganizationPipeline responses: "200": @@ -1525,9 +1529,9 @@ paths: parameters: - name: user_pipeline_name_1 description: |- - The resource name of the pipeline, which allows its access by parent user - and ID. - - Format: `organizations/{org.id}/pipelines/{pipeline.id}`. + The resource name of the pipeline, which allows its access by parent + organization and ID. + - Format: `organizations/{organization.id}/pipelines/{pipeline.id}`. in: path required: true type: string @@ -3393,11 +3397,8 @@ paths: post: summary: Check the availibity of a resource name description: |- - Check the availibity of a resource name. The name should be in the formats: - - users//pipelines/ - - users//connectors/ - - organizations//pipelines/ - - organizations//connectors/ + Check whether a resource name is already in use. Currently this endpoint + only supports pipeline and connector resource names. operationId: PipelinePublicService_CheckName responses: "200": @@ -3429,9 +3430,10 @@ definitions: - NAME_AVAILABLE - NAME_UNAVAILABLE description: |- - - NAME_AVAILABLE: Available. + Name defines the availability of a resource name. + + - NAME_AVAILABLE: Available. - NAME_UNAVAILABLE: Unavailable. - title: Availability of Name HealthCheckResponseServingStatus: type: string enum: @@ -3447,9 +3449,13 @@ definitions: target: type: string title: |- - The target pipeline - - Format: `users/{user.id}/pipelines/{pipeline.id}` or `organizations/{org.id}/pipelines/{pipeline.id}` - description: CloneOrganizationPipelineRequest represents a request to clone a pipeline owned by a organization. + The target pipeline name. It can be under a user or an organization + namespace, so the following formats are accepted: + - `users/{user.id}/pipelines/{pipeline.id}` + - `organizations/{organization.id}/pipelines/{pipeline.id}` + description: |- + CloneOrganizationPipelineRequest represents a request to clone a pipeline + owned by an organization. required: - target PipelinePublicServiceCloneUserPipelineBody: @@ -3458,9 +3464,13 @@ definitions: target: type: string title: |- - The target pipeline - - Format: `users/{user.id}/pipelines/{pipeline.id}` or `organizations/{org.id}/pipelines/{pipeline.id}` - description: CloneUserPipelineRequest represents a request to clone a pipeline owned by a user. + The target pipeline name. It can be under a user or an organization + namespace, so the following formats are accepted: + - `users/{user.id}/pipelines/{pipeline.id}` + - `organizations/{organization.id}/pipelines/{pipeline.id}` + description: |- + CloneUserPipelineRequest represents a request to clone a pipeline owned by a + user. required: - target PipelinePublicServiceConnectOrganizationConnectorBody: @@ -3957,11 +3967,12 @@ definitions: name: type: string title: |- - The name of the resource to be checked, should be in the formats: - - users//pipelines/ - - users//connectors/ - - organizations//pipelines/ - - organizations//connectors/ + The name of the resource to be checked. For the moment, only pipeline and + connector names can be checked. The following formats are accepted: + - `users/{user.id}/pipelines/{pipeline.id}` + - `users/{user.id}/connectors/{connector.id}` + - `organizations/{organization.id}/pipelines/{pipeline.id}` + - `organizations/{organization.id}/connectors/{connector.id}` description: |- CheckNameRequest represents a request to verify if a name is available. @@ -3972,10 +3983,8 @@ definitions: properties: availability: $ref: '#/definitions/CheckNameResponseName' - title: Availability - description: |- - CheckNameResponse contains the availability of a name - of resource that's using it. + description: The availability of the requested name. + description: CheckNameResponse contains the availability of a resource name. v1betaCloneOrganizationPipelineResponse: type: object properties: