From 6f5b71a96ea9d383cad2a5b3c6a7afacb48cff55 Mon Sep 17 00:00:00 2001 From: Simon Richardson Date: Mon, 9 May 2022 19:31:04 +0100 Subject: [PATCH 1/2] docs(template): Document template too large Changes: ErrorResponse for /api/v2/template/apply The following adds documentation about a new feature that issues an error message if the template is too large. Currently, this targets only cloud, but we should consider this for OSS. I'll open this up for discussion, if in doubt I'll move this to cloud only as a divergent API. --- contracts/cloud.json | 29 ++++++++++++++++++++++++++++ contracts/cloud.yml | 16 +++++++++++++++ contracts/common.yml | 16 +++++++++++++++ contracts/oss.json | 29 ++++++++++++++++++++++++++++ contracts/oss.yml | 16 +++++++++++++++ contracts/ref/cloud.yml | 16 +++++++++++++++ contracts/ref/oss.yml | 16 +++++++++++++++ src/README.md | 4 ++-- src/common/paths/templates_apply.yml | 6 ++++++ 9 files changed, 146 insertions(+), 2 deletions(-) diff --git a/contracts/cloud.json b/contracts/cloud.json index 636f9c7b..4ead1640 100644 --- a/contracts/cloud.json +++ b/contracts/cloud.json @@ -5452,6 +5452,35 @@ } } }, + "413": { + "description": "Template too large", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/TemplateSummary" + }, + { + "type": "object", + "required": [ + "message", + "code" + ], + "properties": { + "message": { + "type": "string" + }, + "code": { + "type": "string" + } + } + } + ] + } + } + } + }, "422": { "description": "Template failed validation", "content": { diff --git a/contracts/cloud.yml b/contracts/cloud.yml index 86001208..6115100e 100644 --- a/contracts/cloud.yml +++ b/contracts/cloud.yml @@ -3564,6 +3564,22 @@ paths: application/json: schema: $ref: '#/components/schemas/TemplateSummary' + '413': + description: Template too large + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/TemplateSummary' + - type: object + required: + - message + - code + properties: + message: + type: string + code: + type: string '422': description: Template failed validation content: diff --git a/contracts/common.yml b/contracts/common.yml index 489f9f33..68351386 100644 --- a/contracts/common.yml +++ b/contracts/common.yml @@ -3446,6 +3446,22 @@ paths: application/json: schema: $ref: '#/components/schemas/TemplateSummary' + '413': + description: Template too large + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/TemplateSummary' + - type: object + required: + - message + - code + properties: + message: + type: string + code: + type: string '422': description: Template failed validation content: diff --git a/contracts/oss.json b/contracts/oss.json index 74cbd876..3e569239 100644 --- a/contracts/oss.json +++ b/contracts/oss.json @@ -5456,6 +5456,35 @@ } } }, + "413": { + "description": "Template too large", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "$ref": "#/components/schemas/TemplateSummary" + }, + { + "type": "object", + "required": [ + "message", + "code" + ], + "properties": { + "message": { + "type": "string" + }, + "code": { + "type": "string" + } + } + } + ] + } + } + } + }, "422": { "description": "Template failed validation", "content": { diff --git a/contracts/oss.yml b/contracts/oss.yml index 2d31a1e9..ff1ef332 100644 --- a/contracts/oss.yml +++ b/contracts/oss.yml @@ -3570,6 +3570,22 @@ paths: application/json: schema: $ref: '#/components/schemas/TemplateSummary' + '413': + description: Template too large + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/TemplateSummary' + - type: object + required: + - message + - code + properties: + message: + type: string + code: + type: string '422': description: Template failed validation content: diff --git a/contracts/ref/cloud.yml b/contracts/ref/cloud.yml index 11552679..608da296 100644 --- a/contracts/ref/cloud.yml +++ b/contracts/ref/cloud.yml @@ -11436,6 +11436,22 @@ paths: $ref: '#/components/schemas/TemplateSummary' description: | Success. The package applied successfully. Returns a diff and summary of the run. The summary contains newly created resources. The diff compares the initial state to the state after the package applied. This corresponds to `"dryRun": true`. + "413": + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/TemplateSummary' + - properties: + code: + type: string + message: + type: string + required: + - message + - code + type: object + description: Template too large "422": content: application/json: diff --git a/contracts/ref/oss.yml b/contracts/ref/oss.yml index a4ccbb6e..c2b891ee 100644 --- a/contracts/ref/oss.yml +++ b/contracts/ref/oss.yml @@ -13404,6 +13404,22 @@ paths: $ref: '#/components/schemas/TemplateSummary' description: | Success. The package applied successfully. Returns a diff and summary of the run. The summary contains newly created resources. The diff compares the initial state to the state after the package applied. This corresponds to `"dryRun": true`. + "413": + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/TemplateSummary' + - properties: + code: + type: string + message: + type: string + required: + - message + - code + type: object + description: Template too large "422": content: application/json: diff --git a/src/README.md b/src/README.md index a26cf2e4..c6a8d8d1 100644 --- a/src/README.md +++ b/src/README.md @@ -1,8 +1,8 @@ # When APIs Drift -Within this (`src`) directory, you will find all API resource definitions. OSS/Cloud specific resources are defined in the `src/oss` and `src/cloud` directories respectively. When a shared type drifts, it will need to be removed from `common` and placed into the resource type's directory within the platform (cloud/oss) specific directory. Caution should be exercized so as to avoid stale references in complex resource types. +Within this (`src`) directory, you will find all API resource definitions. OSS/Cloud specific resources are defined in the `src/oss` and `src/cloud` directories respectively. When a shared type drifts, it will need to be removed from `common` and placed into the resource type's directory within the platform (cloud/oss) specific directory. Caution should be exercised to avoid stale references in complex resource types. -For example if it there was some cloud only changes to the `AddResourceMemberRequestBody` type, one would: +If there was some cloud only changes to the `AddResourceMemberRequestBody` type, one would: ```sh # copy the type to the platform where the type has changed copy src/common/schemas/AddResourceMemberRequestBody.yml src/cloud/schemas/AddResourceMemberRequestBody.yml diff --git a/src/common/paths/templates_apply.yml b/src/common/paths/templates_apply.yml index 10ecccfc..5ebb42ef 100644 --- a/src/common/paths/templates_apply.yml +++ b/src/common/paths/templates_apply.yml @@ -41,6 +41,12 @@ post: application/json: schema: $ref: "../schemas/TemplateSummary.yml" + "413": + description: Template too large + content: + application/json: + schema: + $ref: "../schemas/TemplateSummaryError.yml" "422": description: Template failed validation content: From 174a2482774d7c08a34bacc04877e62f5cee949c Mon Sep 17 00:00:00 2001 From: Simon Richardson Date: Wed, 11 May 2022 11:45:30 +0100 Subject: [PATCH 2/2] fix(template): Duplicate file for TemplateTooLarge The following just ensures that we don't inline the reference for errors that have the same body but different error code. This is shame, but I can see why. The fix is simple, just create a new template reference that duplicates the TemplateSummaryError. --- src/common/paths/templates_apply.yml | 2 +- src/common/schemas/TemplateTooLargeError.yml | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 src/common/schemas/TemplateTooLargeError.yml diff --git a/src/common/paths/templates_apply.yml b/src/common/paths/templates_apply.yml index 5ebb42ef..0fd94b1c 100644 --- a/src/common/paths/templates_apply.yml +++ b/src/common/paths/templates_apply.yml @@ -46,7 +46,7 @@ post: content: application/json: schema: - $ref: "../schemas/TemplateSummaryError.yml" + $ref: "../schemas/TemplateTooLargeError.yml" "422": description: Template failed validation content: diff --git a/src/common/schemas/TemplateTooLargeError.yml b/src/common/schemas/TemplateTooLargeError.yml new file mode 100644 index 00000000..f489e3ed --- /dev/null +++ b/src/common/schemas/TemplateTooLargeError.yml @@ -0,0 +1,9 @@ + allOf: + - $ref: "./TemplateSummary.yml" + - type: object + required: [message, code] + properties: + message: + type: string + code: + type: string