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 636f9c7be..4ead16409 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 86001208c..6115100e1 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 489f9f337..683513862 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 74cbd8760..3e5692398 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 2d31a1e9e..ff1ef3325 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 11552679c..608da2968 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 a4ccbb6ee..c2b891eed 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 a26cf2e4c..c6a8d8d18 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 10ecccfc2..5ebb42ef0 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 5ebb42ef0..0fd94b1c5 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 000000000..f489e3ed4 --- /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