From a91a3cf3979baee01003fd3bd2834e4f8310638a Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Fri, 13 Sep 2024 11:00:05 -0400 Subject: [PATCH 1/6] Adding description for 2 new APIs Adding definitions for SOP Update Check/Download actions. --- Data-Gateway.json | 88 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/Data-Gateway.json b/Data-Gateway.json index 359fcc7..e595927 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -667,6 +667,19 @@ ], "title": "Application Telemetry - SOP", "type": "object" + }, + "Update.Sop.Check": { + "description": "Object returning the value of the version of the latest application package available.", + "properties": { + "updateVersion": { + "description": "Latest found version of the application package.", + "example": "1.12.5", + "type": "string" + } + }, + "required": [ "updateVersion" ], + "title": "Update SOP Check - latest application package version", + "type": "object" } }, "securitySchemes": { @@ -1808,6 +1821,81 @@ "Telemetry" ] } + }, + "/API/Update/Sop/Check/": { + "get": { + "description": "Retrieves the latest available version of the package for the running application. Version depends on the channel associated with the current tenant, or channel mentioned in the request, or default channel value. Applicable channel would be calculated on the server for each request.", + "operationId": "/API/Update/Sop/Check/Get", + "parameters": [ + { + "in": "query", + "name": "channel", + "schema": { + "type": "string" + }, + "required": false, + "description": "Name of the deploy channel where to look for the latest version of the application package." + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Update.Sop.Check" + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "tags": [ + "SOP Update" + ] + } + }, + "/API/Update/Sop/Download/": { + "get": { + "description": "Receives a stream of the ZIP archive content to be saved and that represents requested application update package.", + "operationId": "/API/Update/Sop/Download/Get", + "parameters": [ + { + "in": "query", + "name": "channel", + "schema": { + "type": "string" + }, + "required": false, + "description": "Name of the deploy channel where to look for the latest version of the application package." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/zip": { + "type": "string", + "format": "binary" + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "tags": [ + "SOP Update" + ] + } } }, "security": [ From ba1b7306e35e19e0f148bf27c22efaf49c45f749 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Wed, 6 Nov 2024 12:02:40 -0500 Subject: [PATCH 2/6] Updating schema with missing wrapper Adding missing schema definition --- Data-Gateway.json | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Data-Gateway.json b/Data-Gateway.json index f4d82fd..93fe9e9 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -1885,8 +1885,10 @@ "description": "OK", "content": { "application/zip": { - "type": "string", - "format": "binary" + "schema": { + "type": "string", + "format": "binary" + } } } }, From 8532173707d73bd364033dff0a08af8eba3486d7 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Mon, 11 Nov 2024 16:42:08 -0500 Subject: [PATCH 3/6] Updating to reflect upcoming renaming Using correct name to reference application as Shield --- Data-Gateway.json | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Data-Gateway.json b/Data-Gateway.json index 93fe9e9..cca55ca 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -673,7 +673,7 @@ "title": "Application Telemetry - SOP", "type": "object" }, - "Update.Sop.Check": { + "Update.Shield.Check": { "description": "Object returning the value of the version of the latest application package available.", "properties": { "updateVersion": { @@ -683,7 +683,7 @@ } }, "required": [ "updateVersion" ], - "title": "Update SOP Check - latest application package version", + "title": "Update SHIELD Check - latest application package version", "type": "object" } }, @@ -1827,10 +1827,10 @@ ] } }, - "/API/Update/Sop/Check/": { + "/API/Update/Shield/Check/": { "get": { "description": "Retrieves the latest available version of the package for the running application. Version depends on the channel associated with the current tenant, or channel mentioned in the request, or default channel value. Applicable channel would be calculated on the server for each request.", - "operationId": "/API/Update/Sop/Check/Get", + "operationId": "/API/Update/Shield/Check/Get", "parameters": [ { "in": "query", @@ -1847,7 +1847,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Update.Sop.Check" + "$ref": "#/components/schemas/Update.Shield.Check" } } }, @@ -1861,14 +1861,14 @@ } }, "tags": [ - "SOP Update" + "Update" ] } }, - "/API/Update/Sop/Download/": { + "/API/Update/Shield/Download/": { "get": { "description": "Receives a stream of the ZIP archive content to be saved and that represents requested application update package.", - "operationId": "/API/Update/Sop/Download/Get", + "operationId": "/API/Update/Shield/Download/Get", "parameters": [ { "in": "query", @@ -1900,7 +1900,7 @@ } }, "tags": [ - "SOP Update" + "Update" ] } } From 50642c3e0bc9be5ab81bac84b85f86f0ac652eb4 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Mon, 6 Jan 2025 18:07:56 -0500 Subject: [PATCH 4/6] Storing changes Saving work progress --- Data-Gateway.json | 661 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 652 insertions(+), 9 deletions(-) diff --git a/Data-Gateway.json b/Data-Gateway.json index 1563d45..43bf1f8 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -28,6 +28,27 @@ "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } + }, + "channelName": { + "description": "Name of the deploy channel to operate against.", + "in": "path", + "name": "channelName", + "required": true, + "schema": { + "example": "beta", + "type": "string" + } + }, + "channelRing": { + "description": "Integer number representing ring to operate against.", + "in": "path", + "name": "number", + "required": true, + "schema": { + "example": 1, + "type": "integer", + "minimum": 0 + } } }, "responses": { @@ -685,6 +706,80 @@ "required": [ "updateVersion" ], "title": "Update SHIELD Check - latest application package version", "type": "object" + }, + "Update.Shield.Channel": { + "description": "Object containing deploy channel configuration.", + "properties": { + "latest": { + "description": "Version number of the latest update available to the chanel.", + "example": "1.12.5", + "type": "string" + }, + "name": { + "description": "(Unique) Name of the update channel that this configuration belongs to.", + "example": "stable", + "type": "string" + }, + "previous": { + "description": "Version number of the package that was available until the newest deploy.", + "example": "1.12.4", + "type": "string" + } + }, + "required": [ "latest", "name", "previous" ], + "title": "Update SHIELD Channel - configuration entry", + "type": "object" + }, + "Update.Shield.Channel.Ring": { + "description": "Object containing channel ring configuration.", + "properties": { + "latest": { + "description": "Flag that indicates if the ring should be operating off of the latest version number provided by the channel (`true`) or the previous (`false`).", + "example": true, + "type": "boolean" + }, + "number": { + "description": "Ring number that this configuration belongs to.", + "example": 1, + "type": "integer", + "minimum": 0 + } + }, + "required": [ "latest", "number" ], + "title": "Update SHIELD Channel Ring - configuration entry", + "type": "object" + }, + "Update.Shield.Tenant": { + "description": "Object containing tenant update configuration.", + "properties": { + "alphaEnabled": { + "description": "Flag that indicates if the current tenant is allowed to request alpha builds (`true`) or not (`false`).", + "example": false, + "type": "boolean" + }, + "channel": { + "description": "Name of the deploy channel.", + "example": "stable", + "type": "string" + }, + "ring": { + "description": "Ring number that the client is a member of for the current chanel.", + "example": 1, + "type": "integer" + }, + "tenantId": { + "description": "Tenant ID that the configuration belongs to.", + "example": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + } + }, + "required": [ "alphaEnabled", "channel", "ring", "tenantId" ], + "title": "Update SHIELD Tenant - configuration entry", + "type": "object" } }, "securitySchemes": { @@ -1827,21 +1922,375 @@ ] } }, - "/API/Update/Shield/Check/": { + "/API/Update/Shield/Channel/": { "get": { - "description": "Retrieves the latest available version of the package for the running application. Version depends on the channel associated with the current tenant, or channel mentioned in the request, or default channel value. Applicable channel would be calculated on the server for each request.", - "operationId": "/API/Update/Shield/Check/Get", + "description": "Retrieves all of the channel configurations that are present in the update service.", + "operationId": "/API/Update/Shield/Channel/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Update.Shield.Channel" + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "tags": [ + "Update" + ] + } + }, + "/API/Update/Shield/Channel/{channelName}/": { + "get": { + "description": "Retrieves configuration for the specific channel from the update service.", + "operationId": "/API/Update/Shield/Channel/:channelName/Get", "parameters": [ { - "in": "query", - "name": "channel", - "schema": { - "type": "string" + "$ref": "#/components/parameters/channelName" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Update.Shield.Channel" + } + } }, - "required": false, - "description": "Name of the deploy channel where to look for the latest version of the application package." + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Retrieves Specific Channel Configuration", + "tags": [ + "Update" + ] + }, + "patch": { + "description": "Updates (or adds when missing) channel configuration.", + "operationId": "/API/Update/Shield/Channel/:channelName/Patch", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" } ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "Channel Configuration Details": { + "description": "Example channel configuration object.", + "summary": "Channel Configuration", + "value": { + "latest": "1.12.5", + "previous": "1.12.4" + } + } + }, + "schema": { + "type": "object", + "properties": { + "latest": { + "description": "Flag that indicates if the ring should be operating off of the latest version number provided by the channel (`true`) or the previous (`false`).", + "example": "true", + "type": "boolean" + }, + "number": { + "description": "Ring number that this configuration belongs to.", + "example": 1, + "type": "integer", + "minimum": 0 + } + } + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Channel Configuration Details": { + "description": "Example object returned on creation or update.", + "summary": "Channel Configuration", + "value": { + "latest": "1.12.5", + "name": "stable", + "previous": "1.12.4" + } + } + }, + "schema": { + "$ref": "#/components/schemas/Update.Shield.Channel" + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Modifies Channel Configuration", + "tags": [ + "Update" + ] + }, + "delete": { + "description": "Deletes configuration of the specific channel.", + "operationId": "/API/Update/Shield/Channel/:channelName/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + } + ], + "responses": { + "204": { + "description": "Deleted Successfully" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Delete Specified Channel Configuration", + "tags": [ + "Update" + ] + } + }, + "/API/Update/Shield/Channel/{channelName}/Ring/": { + "get": { + "description": "Retrieves all of the ring configurations for a channel that are present in the update service.", + "operationId": "/API/Update/Shield/Channel/:channelName/Ring/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Update.Shield.Channel.Ring" + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "tags": [ + "Update" + ] + } + }, + "/API/Update/Shield/Channel/{channelName}/Ring/{number}/": { + "get": { + "description": "Retrieves configuration for the specific channel ring from the update service.", + "operationId": "/API/Update/Shield/Channel/:channelName/Ring/:number/Get", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + }, + { + "$ref": "#/components/parameters/channelRing" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Update.Shield.Channel.Ring" + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Retrieves Specific Channel Ring Configuration", + "tags": [ + "Update" + ] + }, + "patch": { + "description": "Updates (or adds when missing) channel ring configuration.", + "operationId": "/API/Update/Shield/Channel/:channelName/Ring/:number/Patch", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + }, + { + "$ref": "#/components/parameters/channelRing" + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "Channel Ring Configuration Details": { + "description": "Example channel ring configuration object.", + "summary": "Channel Ring Configuration", + "value": { + "latest": true + } + } + }, + "schema": { + "type": "object", + "properties": { + "latest": { + "description": "Flag that indicates if the ring should be operating off of the latest version number provided by the channel (`true`) or the previous (`false`).", + "example": true, + "type": "boolean" + } + } + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Channel Ring Configuration Details": { + "description": "Example object returned on creation or update.", + "summary": "Channel Ring Configuration", + "value": { + "latest": true, + "number": 1 + } + } + }, + "schema": { + "$ref": "#/components/schemas/Update.Shield.Channel.Ring" + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Modifies Channel Ring Configuration", + "tags": [ + "Update" + ] + }, + "delete": { + "description": "Deletes configuration of the specific channel ring.", + "operationId": "/API/Update/Shield/Channel/:channelName/Ring/:number/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + }, + { + "$ref": "#/components/parameters/channelRing" + } + ], + "responses": { + "204": { + "description": "Deleted Successfully" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Delete Specified Channel Ring Configuration", + "tags": [ + "Update" + ] + } + }, + "/API/Update/Shield/Channel/:channelName/Version/:version/": { + "": { + "description": "", + "operationId": "", + "responses": { + + }, + "tags": [ + + ] + } + }, + "/API/Update/Shield/Check/": { + "get": { + "description": "Retrieves the latest available version of the package for the running application. Version depends on the channel associated with the current tenant, or channel mentioned in the request, or default channel value. Applicable channel would be calculated on the server for each request.", + "operationId": "/API/Update/Shield/Check/Get", "responses": { "200": { "content": { @@ -1903,6 +2352,200 @@ "Update" ] } + }, + "/API/Update/Shield/Download/Channel/:channelName/": { + "": { + "description": "", + "operationId": "", + "responses": { + + }, + "tags": [ + + ] + } + }, + "/API/Update/Shield/Tenant/": { + "get": { + "description": "Retrieves all tenant configurations present in the update service.", + "operationId": "/API/Update/Shield/Tenant/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Update.Shield.Tenant" + } + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "tags": [ + "Update" + ] + } + }, + "/API/Update/Shield/Tenant/{tenantId}/": { + "get": { + "description": "Retrieves configuration for the specific tenant from the update service.", + "operationId": "/API/Update/Shield/Tenant/:tenantId/Get", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Update.Shield.Tenant" + } + } + }, + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Retrieves Specific Tenant Configuration", + "tags": [ + "Update" + ] + }, + "patch": { + "description": "Updates (or adds when missing) tenant configuration.", + "operationId": "/API/Update/Shield/Tenant/:tenantId/Patch", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + } + ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "Tenant Configuration Details": { + "description": "Example tenant configuration object.", + "summary": "Tenant Configuration", + "value": { + "alphaEnabled": false, + "channel": "stable", + "ring": 1 + } + } + }, + "schema": { + "type": "object", + "properties": { + "alphaEnabled": { + "description": "Flag that indicates if the current tenant is allowed to request alpha builds (`true`) or not (`false`).", + "example": false, + "type": "boolean" + }, + "channel": { + "description": "Name of the deploy channel.", + "example": "stable", + "type": "string" + }, + "ring": { + "description": "Ring number that the client is a member of for the current chanel.", + "example": 1, + "type": "integer" + } + } + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Tenant Configuration Details": { + "description": "Example object returned on creation or update.", + "summary": "Tenant Configuration", + "value": { + "alphaEnabled": false, + "channel": "stable", + "ring": 1, + "tenantId": "a2a1698d-a3e0-42d3-96a4-47eb3e8f7dd1" + } + } + }, + "schema": { + "$ref": "#/components/schemas/Update.Shield.Tenant" + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Modifies Tenant Configuration", + "tags": [ + "Update" + ] + }, + "delete": { + "description": "Deletes configuration for the specific tenant.", + "operationId": "/API/Update/Shield/Tenant/:tenantId/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + } + ], + "responses": { + "204": { + "description": "Deleted Successfully" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Delete Specified Tenant Configuration", + "tags": [ + "Update" + ] + } } }, "security": [ From ca9639356458ea5d2c630ecf2639ebf3b777236b Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Tue, 7 Jan 2025 11:57:13 -0500 Subject: [PATCH 5/6] Finish remaining configurations Ensure all endpoints are properly described. Adding missing properties to present user-friendly output --- Data-Gateway.json | 154 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 121 insertions(+), 33 deletions(-) diff --git a/Data-Gateway.json b/Data-Gateway.json index 43bf1f8..07d1b99 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -49,6 +49,16 @@ "type": "integer", "minimum": 0 } + }, + "version": { + "description": "Version of the application package.", + "in": "path", + "name": "version", + "required": true, + "schema": { + "example": "1.12.5", + "type": "string" + } } }, "responses": { @@ -1950,6 +1960,7 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, + "summary": "Retrieves All Channel Configurations", "tags": [ "Update" ] @@ -2092,7 +2103,7 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Delete Specified Channel Configuration", + "summary": "Deletes Specified Channel Configuration", "tags": [ "Update" ] @@ -2102,6 +2113,11 @@ "get": { "description": "Retrieves all of the ring configurations for a channel that are present in the update service.", "operationId": "/API/Update/Shield/Channel/:channelName/Ring/Get", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + } + ], "responses": { "200": { "content": { @@ -2126,6 +2142,7 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, + "summary": "Retrieves All Ring Configurations", "tags": [ "Update" ] @@ -2239,7 +2256,7 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Modifies Channel Ring Configuration", + "summary": "Modifies Specific Channel Ring Configuration", "tags": [ "Update" ] @@ -2269,21 +2286,54 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Delete Specified Channel Ring Configuration", + "summary": "Deletes Specific Channel Ring Configuration", "tags": [ "Update" ] } }, - "/API/Update/Shield/Channel/:channelName/Version/:version/": { - "": { - "description": "", - "operationId": "", + "/API/Update/Shield/Channel/{channelName}/Version/{version}/": { + "post": { + "description": "Uploads new version of the update package for SHIELD in a specific channel.", + "operationId": "/API/Update/Shield/Channel/:channelName/Version/:version/Post", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + }, + { + "$ref": "#/components/parameters/version" + } + ], + "requestBody": { + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, "responses": { - + "204": { + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } }, + "summary": "Uploads New Application Package", "tags": [ - + "Update" ] } }, @@ -2302,33 +2352,50 @@ }, "description": "OK" }, - "400": { - "$ref": "#/components/responses/400" - }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, + "summary": "Retrieves Latest Application Version Number", "tags": [ "Update" ] } }, - "/API/Update/Shield/Download/": { + "/API/Update/Shield/Check/Channel/{channelName}/": { "get": { - "description": "Receives a stream of the ZIP archive content to be saved and that represents requested application update package.", - "operationId": "/API/Update/Shield/Download/Get", + "description": "Retrieves the latest available version of the package for the running application for the specific channel.", + "operationId": "/API/Update/Shield/Check/Channel/:channelName/Get", "parameters": [ { - "in": "query", - "name": "channel", - "schema": { - "type": "string" - }, - "required": false, - "description": "Name of the deploy channel where to look for the latest version of the application package." + "$ref": "#/components/parameters/channelName" } ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Update.Shield.Check" + } + } + }, + "description": "OK" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } + }, + "summary": "Retrieves Application Version Number For Specific Channel", + "tags": [ + "Update" + ] + } + }, + "/API/Update/Shield/Download/": { + "get": { + "description": "Sends a stream of the ZIP archive content to be saved that represents requested application update package.", + "operationId": "/API/Update/Shield/Download/Get", "responses": { "200": { "description": "OK", @@ -2341,27 +2408,47 @@ } } }, - "400": { - "$ref": "#/components/responses/400" - }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, + "summary": "Streams File Content To Download", "tags": [ "Update" ] } }, - "/API/Update/Shield/Download/Channel/:channelName/": { - "": { - "description": "", - "operationId": "", + "/API/Update/Shield/Download/Channel/{channelName}/": { + "get": { + "description": "Sends a stream of the ZIP archive content to be saved that represents requested application update package for the specific channel.", + "operationId": "/API/Update/Shield/Download/Channel/:channelName/Get", + "parameters": [ + { + "$ref": "#/components/parameters/channelName" + } + ], "responses": { - + "200": { + "description": "OK", + "content": { + "application/zip": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." + } }, + "summary": "Streams File Content From Specific Channel To Download", "tags": [ - + "Update" ] } }, @@ -2393,6 +2480,7 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, + "summary": "Retrieves All Tenant Configurations", "tags": [ "Update" ] @@ -2514,7 +2602,7 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Modifies Tenant Configuration", + "summary": "Modifies Specific Tenant Configuration", "tags": [ "Update" ] @@ -2541,7 +2629,7 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Delete Specified Tenant Configuration", + "summary": "Deletes Specific Tenant Configuration", "tags": [ "Update" ] From 03eb10206b31b17a93335849c9ee3d43ead73293 Mon Sep 17 00:00:00 2001 From: Elliot Huffman Date: Wed, 15 Jan 2025 14:06:22 -0500 Subject: [PATCH 6/6] Polish Spec Update wording to indicate which tenant and permissions are required for update service configurations. Update the tags to be more descriptive. Formatting. --- Data-Gateway.json | 102 +++++++++++++++++++++++++++------------------- 1 file changed, 60 insertions(+), 42 deletions(-) diff --git a/Data-Gateway.json b/Data-Gateway.json index 07d1b99..f42b6a4 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -713,12 +713,14 @@ "type": "string" } }, - "required": [ "updateVersion" ], + "required": [ + "updateVersion" + ], "title": "Update SHIELD Check - latest application package version", "type": "object" }, "Update.Shield.Channel": { - "description": "Object containing deploy channel configuration.", + "description": "Channel configuration for the SHIELD update service.", "properties": { "latest": { "description": "Version number of the latest update available to the chanel.", @@ -731,13 +733,17 @@ "type": "string" }, "previous": { - "description": "Version number of the package that was available until the newest deploy.", + "description": "Version number of the number that is being replaced via ring deployment, available to all rings at the minimum.", "example": "1.12.4", "type": "string" } }, - "required": [ "latest", "name", "previous" ], - "title": "Update SHIELD Channel - configuration entry", + "required": [ + "latest", + "name", + "previous" + ], + "title": "SHIELD Update - Channel", "type": "object" }, "Update.Shield.Channel.Ring": { @@ -755,7 +761,10 @@ "minimum": 0 } }, - "required": [ "latest", "number" ], + "required": [ + "latest", + "number" + ], "title": "Update SHIELD Channel Ring - configuration entry", "type": "object" }, @@ -787,7 +796,12 @@ "type": "string" } }, - "required": [ "alphaEnabled", "channel", "ring", "tenantId" ], + "required": [ + "alphaEnabled", + "channel", + "ring", + "tenantId" + ], "title": "Update SHIELD Tenant - configuration entry", "type": "object" } @@ -1934,7 +1948,7 @@ }, "/API/Update/Shield/Channel/": { "get": { - "description": "Retrieves all of the channel configurations that are present in the update service.", + "description": "Retrieves all of the channel configurations that are present in the update service. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Channel/Get", "responses": { "200": { @@ -1962,13 +1976,13 @@ }, "summary": "Retrieves All Channel Configurations", "tags": [ - "Update" + "SHIELD - Update" ] } }, "/API/Update/Shield/Channel/{channelName}/": { "get": { - "description": "Retrieves configuration for the specific channel from the update service.", + "description": "Retrieves configuration for the specific channel from the update service. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Channel/:channelName/Get", "parameters": [ { @@ -1998,11 +2012,11 @@ }, "summary": "Retrieves Specific Channel Configuration", "tags": [ - "Update" + "SHIELD - Update" ] }, "patch": { - "description": "Updates (or adds when missing) channel configuration.", + "description": "Updates (or adds when missing) the specified channel configuration. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Channel/:channelName/Patch", "parameters": [ { @@ -2076,13 +2090,13 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Modifies Channel Configuration", + "summary": "Upserts Channel Configuration", "tags": [ - "Update" + "SHIELD - Update" ] }, "delete": { - "description": "Deletes configuration of the specific channel.", + "description": "Deletes the specified channel configuration and associated rings. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Channel/:channelName/Delete", "parameters": [ { @@ -2103,15 +2117,15 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Deletes Specified Channel Configuration", + "summary": "Deletes the Specified Channel", "tags": [ - "Update" + "SHIELD - Update" ] } }, "/API/Update/Shield/Channel/{channelName}/Ring/": { "get": { - "description": "Retrieves all of the ring configurations for a channel that are present in the update service.", + "description": "Retrieves all of the ring configurations for a channel that are present in the update service. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Channel/:channelName/Ring/Get", "parameters": [ { @@ -2144,13 +2158,13 @@ }, "summary": "Retrieves All Ring Configurations", "tags": [ - "Update" + "SHIELD - Update" ] } }, "/API/Update/Shield/Channel/{channelName}/Ring/{number}/": { "get": { - "description": "Retrieves configuration for the specific channel ring from the update service.", + "description": "Retrieves configuration for the specific channel ring from the update service. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Channel/:channelName/Ring/:number/Get", "parameters": [ { @@ -2183,11 +2197,11 @@ }, "summary": "Retrieves Specific Channel Ring Configuration", "tags": [ - "Update" + "SHIELD - Update" ] }, "patch": { - "description": "Updates (or adds when missing) channel ring configuration.", + "description": "Updates (or adds when missing) channel ring configuration. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Channel/:channelName/Ring/:number/Patch", "parameters": [ { @@ -2258,11 +2272,11 @@ }, "summary": "Modifies Specific Channel Ring Configuration", "tags": [ - "Update" + "SHIELD - Update" ] }, "delete": { - "description": "Deletes configuration of the specific channel ring.", + "description": "Deletes configuration of the specific channel ring. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Channel/:channelName/Ring/:number/Delete", "parameters": [ { @@ -2288,13 +2302,13 @@ }, "summary": "Deletes Specific Channel Ring Configuration", "tags": [ - "Update" + "SHIELD - Update" ] } }, "/API/Update/Shield/Channel/{channelName}/Version/{version}/": { "post": { - "description": "Uploads new version of the update package for SHIELD in a specific channel.", + "description": "Uploads new version of the update package for SHIELD in a specific channel. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Channel/:channelName/Version/:version/Post", "parameters": [ { @@ -2308,7 +2322,7 @@ "content": { "application/octet-stream": { "schema": { - "type": "string", + "type": "string", "format": "binary" } } @@ -2333,7 +2347,7 @@ }, "summary": "Uploads New Application Package", "tags": [ - "Update" + "SHIELD - Update" ] } }, @@ -2358,7 +2372,7 @@ }, "summary": "Retrieves Latest Application Version Number", "tags": [ - "Update" + "SHIELD - Update" ] } }, @@ -2388,7 +2402,7 @@ }, "summary": "Retrieves Application Version Number For Specific Channel", "tags": [ - "Update" + "SHIELD - Update" ] } }, @@ -2414,7 +2428,7 @@ }, "summary": "Streams File Content To Download", "tags": [ - "Update" + "SHIELD - Update" ] } }, @@ -2448,13 +2462,13 @@ }, "summary": "Streams File Content From Specific Channel To Download", "tags": [ - "Update" + "SHIELD - Update" ] } }, "/API/Update/Shield/Tenant/": { "get": { - "description": "Retrieves all tenant configurations present in the update service.", + "description": "Retrieves all tenant configurations present in the update service. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Tenant/Get", "responses": { "200": { @@ -2482,13 +2496,13 @@ }, "summary": "Retrieves All Tenant Configurations", "tags": [ - "Update" + "SHIELD - Update" ] } }, "/API/Update/Shield/Tenant/{tenantId}/": { "get": { - "description": "Retrieves configuration for the specific tenant from the update service.", + "description": "Retrieves configuration for the specific tenant from the update service. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Tenant/:tenantId/Get", "parameters": [ { @@ -2518,11 +2532,11 @@ }, "summary": "Retrieves Specific Tenant Configuration", "tags": [ - "Update" + "SHIELD - Update" ] }, "patch": { - "description": "Updates (or adds when missing) tenant configuration.", + "description": "Updates (or adds when missing) tenant configuration. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Tenant/:tenantId/Patch", "parameters": [ { @@ -2602,13 +2616,13 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Modifies Specific Tenant Configuration", + "summary": "Upserts Specific Tenant Configuration", "tags": [ - "Update" + "SHIELD - Update" ] }, "delete": { - "description": "Deletes configuration for the specific tenant.", + "description": "Deletes configuration for the specific tenant. This endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible form the `SHI Lab` tenant. End user access is restricted.", "operationId": "/API/Update/Shield/Tenant/:tenantId/Delete", "parameters": [ { @@ -2631,7 +2645,7 @@ }, "summary": "Deletes Specific Tenant Configuration", "tags": [ - "Update" + "SHIELD - Update" ] } } @@ -2671,6 +2685,10 @@ { "description": "Collects data from the various SHI Lab products.", "name": "Telemetry" + }, + { + "name": "SHIELD - Update", + "description": "Update Service Configuration for SHIELD." } ] -} \ No newline at end of file +}