From cc1bcc26267432df8957f618437b6efca8f9ed3e Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Thu, 13 Mar 2025 12:57:44 -0400 Subject: [PATCH 1/6] Adding new endpoints to handle Customer operations Defining endpoints to handle get/patch/delete operations for customer-related data Including new parameter and schemas use with the endpoints --- Data-Gateway.json | 267 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 267 insertions(+) diff --git a/Data-Gateway.json b/Data-Gateway.json index 19efb91..602e398 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -59,6 +59,20 @@ "example": "1.12.5", "type": "string" } + }, + "customerId": { + "description": "The object ID of the customer value to operate against.", + "in": "path", + "name": "customerId", + "required": true, + "schema": { + "example": "3b241101-e2bb-4255-8caf-4136c566a962", + "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" + } } }, "responses": { @@ -804,6 +818,65 @@ ], "title": "Update SHIELD Tenant - configuration entry", "type": "object" + }, + "CustomerList.Record": { + "title": "Customer List Record", + "description": "Details of a single entry in the list of customer records", + "properties": { + "customerId": { + "description": "The object ID of the customer record", + "example": "1c4d2f3b-2e4b-4a5b-8c6d-7e8f9a0b1c2d", + "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" + }, + "customerDisplayName": { + "description": "Human readable name for the customer record", + "example": "Contoso - Prod", + "type": "string" + } + }, + "type": "object", + "required": [ + "customerId", + "customerDisplayName" + ] + }, + "Customer.Record": { + "title": "Customer Record", + "description": "Details of a single customer record requested directly that includes additional information", + "properties": { + "customerId": { + "description": "The object ID of the customer record", + "example": "1c4d2f3b-2e4b-4a5b-8c6d-7e8f9a0b1c2d", + "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" + }, + "customerDisplayName": { + "description": "Human readable name for the customer record", + "example": "Contoso - Prod", + "type": "string" + }, + "tenantIdList": { + "description": "Object representing collection of tenant records that include tenant id and name and are associated with this customer record", + "additionalProperties": { + "description": "Human readable name for the tenant record", + "type": "string" + }, + "type": "object" + } + }, + "type": "object", + "required": [ + "customerId", + "customerDisplayName", + "tenantIdList" + ] } }, "securitySchemes": { @@ -2648,6 +2721,200 @@ "SHIELD - Update" ] } + }, + "/API/Customer/" : { + "get": { + "description": "Retrieves the list of unique customer records in the system. This endpoint requires the `Customer.Read.All` or `Customer.ReadWrite.All` scopes (permissions).", + "operationId": "/API/Customer/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/CustomerList.Record" + } + }, + "examples": { + "Example List Of Customer Records": { + "description": "Sample list of unique customer records in the system", + "summary": "Existing Customer Records", + "value": [ + { + "customerId": "5d6e7f8a-9b0c-1d2e-3f4a-5b6c7d8e9f0a", + "customerDisplayName": "Contoso - Legal" + }, + { + "customerId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", + "customerDisplayName": "Contoso - R&D" + } + ] + } + } + } + }, + "description": "OK" + } + }, + "summary": "Retrieves the customer records", + "tags": [ + "Customer Records" + ] + } + }, + "/API/Customer/{customerId}/": { + "get": { + "description": "Retrieves complete details of one customer record including associated list of tenant records. This endpoint requires the `Customer.Read.All` or `Customer.ReadWrite.All` scopes (permissions).", + "operationId": "/API/Customer/:customerId/Get", + "parameters": [ + { + "$ref": "#/components/parameters/customerId" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Customer.Record" + }, + "examples": { + "Example Complete Customer Record": { + "description": "Sample details of one customer record with extended list of associated tenant records", + "summary": "Existing Customer Record", + "value": { + "customerId": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", + "customerDisplayName": "Contoso - Testing", + "tenantIdList": { + "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c": "Contoso - Testing", + "2e3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6a7b": "Contoso - Testing - Staging 1", + "4b5c6d7e-8f9a-0b1c-2d3e-4f5a6b7c8d9e": "Contoso - Testing - Staging 2" + } + } + } + } + } + }, + "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 Details of One Customer Record", + "tags": [ + "Customer Records" + ] + }, + "patch": { + "description": "Update customer record to either create association for provided tenant value, or adjust human readable name, or both. This endpoint requires the `Customer.ReadWrite.All` scope (permission).", + "operationId": "/API/Customer/:customerId/Patch", + "parameters": [ + { + "$ref": "#/components/parameters/customerId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "tenantId": { + "description": "Optional Object ID of the tenant record to operate against.", + "example": "b2fd105a-2594-437e-b934-1a62a51c28b4", + "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" + }, + "displayName": { + "description": "Optional string representing human readable name for the records.", + "example": "Contoso - New Tenant", + "type": "string" + } + } + }, + "examples": { + "Example Request for Tenant Association": { + "description": "Sample payload requesting for the provided tenant record to be associated with referenced customer value", + "summary": "Create Customer Association for Tenant", + "value": { + "tenantId": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d" + } + }, + "Example Request for Tenant Association and Name Update": { + "description": "Sample payload requesting to associate tenant record with the customer value and also update name of the customer record", + "summary": "Update Customer Record Name and Create Customer Association for Tenant", + "value": { + "tenantId": "8f9a0b1c-2d3e-4f5a-6b7c-8d9e0a1b2c3d", + "displayName": "Contoso - R&D East" + } + } + } + } + } + }, + "responses": { + "204": { + "description": "Updated 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": "Update Customer Record", + "tags": [ + "Customer Records" + ] + } + }, + "/API/Customer/{customerId}/Tenant/{tenantId}/": { + "delete": { + "description": "Removes customer association for the specified tenant record. This endpoint requires the `Customer.ReadWrite.All` scope (permission).", + "operationId": "/API/Customer/:customerId/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/customerId" + }, + { + "$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": "Remove Associated Customer value from Tenant Record", + "tags": [ + "Customer Records" + ] + } } }, "security": [ From 69268428cf6203ef7608c34f1ee9f76d53e6b80b Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Thu, 13 Mar 2025 14:48:57 -0400 Subject: [PATCH 2/6] Adding another response Adding response based on the code changes for this endpoint --- Data-Gateway.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Data-Gateway.json b/Data-Gateway.json index 602e398..8d8635a 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -2868,6 +2868,9 @@ "204": { "description": "Updated successfully" }, + "400": { + "$ref": "#/components/responses/400" + }, "401": { "$ref": "#/components/responses/401" }, From 0488b185f134a3639450a60e5f0700d9cb1cec5c Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Fri, 14 Mar 2025 14:57:24 -0400 Subject: [PATCH 3/6] Updating endpoints per business requirements Removing delete operation Adjusting endpoint for patch operation Updating comments --- Data-Gateway.json | 70 +++++++++++++++++------------------------------ 1 file changed, 25 insertions(+), 45 deletions(-) diff --git a/Data-Gateway.json b/Data-Gateway.json index 8d8635a..37e7404 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -862,7 +862,7 @@ "example": "Contoso - Prod", "type": "string" }, - "tenantIdList": { + "tenantList": { "description": "Object representing collection of tenant records that include tenant id and name and are associated with this customer record", "additionalProperties": { "description": "Human readable name for the tenant record", @@ -2787,7 +2787,7 @@ "value": { "customerId": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", "customerDisplayName": "Contoso - Testing", - "tenantIdList": { + "tenantList": { "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c": "Contoso - Testing", "2e3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6a7b": "Contoso - Testing - Staging 1", "4b5c6d7e-8f9a-0b1c-2d3e-4f5a6b7c8d9e": "Contoso - Testing - Staging 2" @@ -2813,13 +2813,15 @@ "tags": [ "Customer Records" ] - }, + } + }, + "/API/Customer/Tenant/{tenantId}/": { "patch": { - "description": "Update customer record to either create association for provided tenant value, or adjust human readable name, or both. This endpoint requires the `Customer.ReadWrite.All` scope (permission).", - "operationId": "/API/Customer/:customerId/Patch", + "description": "Update tenant record to either create association with provided customer value, or adjust human readable name, or both. This endpoint requires the `Customer.ReadWrite.All` scope (permission).", + "operationId": "/API/Customer/Tenant/:tenantId/Patch", "parameters": [ { - "$ref": "#/components/parameters/customerId" + "$ref": "#/components/parameters/tenantId" } ], "requestBody": { @@ -2828,8 +2830,8 @@ "schema": { "type": "object", "properties": { - "tenantId": { - "description": "Optional Object ID of the tenant record to operate against.", + "customerId": { + "description": "Optional Object ID of the customer record to to use during update process.", "example": "b2fd105a-2594-437e-b934-1a62a51c28b4", "format": "uuid", "maxLength": 36, @@ -2846,19 +2848,26 @@ }, "examples": { "Example Request for Tenant Association": { - "description": "Sample payload requesting for the provided tenant record to be associated with referenced customer value", + "description": "Sample payload requesting for the referenced tenant record to be associated with provided customer value", "summary": "Create Customer Association for Tenant", "value": { - "tenantId": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d" + "customerId": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d" } }, "Example Request for Tenant Association and Name Update": { - "description": "Sample payload requesting to associate tenant record with the customer value and also update name of the customer record", - "summary": "Update Customer Record Name and Create Customer Association for Tenant", + "description": "Sample payload requesting to associate tenant record with the customer value and also update name on the tenant record", + "summary": "Update Tenant Record Name and Create Customer Association for Tenant", "value": { - "tenantId": "8f9a0b1c-2d3e-4f5a-6b7c-8d9e0a1b2c3d", + "customerId": "8f9a0b1c-2d3e-4f5a-6b7c-8d9e0a1b2c3d", "displayName": "Contoso - R&D East" } + }, + "Example Request for Tenant Name Update": { + "description": "Sample payload requesting to update name on the tenant record", + "summary": "Update Tenant Record Name", + "value": { + "displayName": "Contoso - R&D North" + } } } } @@ -2877,43 +2886,14 @@ "403": { "$ref": "#/components/responses/403" }, - "500": { - "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." - } - }, - "summary": "Update Customer Record", - "tags": [ - "Customer Records" - ] - } - }, - "/API/Customer/{customerId}/Tenant/{tenantId}/": { - "delete": { - "description": "Removes customer association for the specified tenant record. This endpoint requires the `Customer.ReadWrite.All` scope (permission).", - "operationId": "/API/Customer/:customerId/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/customerId" - }, - { - "$ref": "#/components/parameters/tenantId" - } - ], - "responses": { - "204": { - "description": "Deleted successfully" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" + "404": { + "$ref": "#/components/responses/404" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Remove Associated Customer value from Tenant Record", + "summary": "Update Tenant Record", "tags": [ "Customer Records" ] From db430d3b8c9b41ad13f8f7be941336114caf7656 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Mon, 17 Mar 2025 09:50:22 -0400 Subject: [PATCH 4/6] Small comment updates Adjusting comment text for clarity --- Data-Gateway.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Data-Gateway.json b/Data-Gateway.json index 37e7404..8d69628 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -2758,7 +2758,7 @@ "description": "OK" } }, - "summary": "Retrieves the customer records", + "summary": "Retrieves list of customer records", "tags": [ "Customer Records" ] @@ -2782,7 +2782,7 @@ }, "examples": { "Example Complete Customer Record": { - "description": "Sample details of one customer record with extended list of associated tenant records", + "description": "Sample details of one customer record with list of associated tenant records", "summary": "Existing Customer Record", "value": { "customerId": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", From 4e094af6b1629bcbf464b810f445efef166f3b2b Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Fri, 21 Mar 2025 18:34:31 -0400 Subject: [PATCH 5/6] Update to endpoints Modify schema definitions to reflect use of tenant record and structure instead of customer --- Data-Gateway.json | 268 ++++++++++++++++++++++++++-------------------- 1 file changed, 153 insertions(+), 115 deletions(-) diff --git a/Data-Gateway.json b/Data-Gateway.json index 53ee7ec..91fe55b 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -60,11 +60,11 @@ "type": "string" } }, - "customerId": { - "description": "The object ID of the customer value to operate against.", - "in": "path", - "name": "customerId", - "required": true, + "parentId": { + "description": "The object ID of the parent value to operate against.", + "in": "query", + "name": "parentId", + "required": false, "schema": { "example": "3b241101-e2bb-4255-8caf-4136c566a962", "format": "uuid", @@ -819,12 +819,12 @@ "title": "Update SHIELD Tenant - configuration entry", "type": "object" }, - "CustomerList.Record": { - "title": "Customer List Record", - "description": "Details of a single entry in the list of customer records", + "TenantDetails.Record": { + "title": "Tenant Details Record", + "description": "Information about a single tenant record", "properties": { - "customerId": { - "description": "The object ID of the customer record", + "tenantId": { + "description": "The object ID of the tenant record", "example": "1c4d2f3b-2e4b-4a5b-8c6d-7e8f9a0b1c2d", "format": "uuid", "maxLength": 36, @@ -832,50 +832,42 @@ "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" }, - "customerDisplayName": { - "description": "Human readable name for the customer record", + "displayName": { + "description": "Human readable name for the tenant record", "example": "Contoso - Prod", "type": "string" - } - }, - "type": "object", - "required": [ - "customerId", - "customerDisplayName" - ] - }, - "Customer.Record": { - "title": "Customer Record", - "description": "Details of a single customer record requested directly that includes additional information", - "properties": { - "customerId": { - "description": "The object ID of the customer record", - "example": "1c4d2f3b-2e4b-4a5b-8c6d-7e8f9a0b1c2d", + }, + "parentId": { + "description": "The object ID of the tenant that is considered a parent to this record", + "example": "22354a3f-2e21-4bd2-8327-dc842cfa80c8", "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" }, - "customerDisplayName": { - "description": "Human readable name for the customer record", - "example": "Contoso - Prod", - "type": "string" - }, - "tenantList": { - "description": "Object representing collection of tenant records that include tenant id and name and are associated with this customer record", - "additionalProperties": { - "description": "Human readable name for the tenant record", + "authorizedPrincipalList": { + "description": "List of object IDs that are allowed to access this record and related data.", + "type": "array", + "items": { + "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" }, - "type": "object" + "example": [ + "fd9a6a53-594d-41aa-950a-b21ff41d4688", + "54fc12cd-403d-4c48-be12-86b807e958d3" + ] } }, "type": "object", "required": [ - "customerId", - "customerDisplayName", - "tenantIdList" + "tenantId", + "displayName", + "parentId", + "authorizedPrincipalList" ] } }, @@ -2722,10 +2714,15 @@ ] } }, - "/API/Customer/" : { + "/API/Tenant/" : { "get": { - "description": "Retrieves the list of unique customer records in the system. This endpoint requires the `Customer.Read.All` or `Customer.ReadWrite.All` scopes (permissions).", - "operationId": "/API/Customer/Get", + "description": "Retrieves the list of tenant records. Can use filter by parent ID limit the results. This endpoint requires the `Tenant.Read.All` or `Tenant.ReadWrite.All` scopes (permissions).", + "operationId": "/API/Tenant/Get", + "parameters": [ + { + "$ref": "#/components/parameters/parentId" + } + ], "responses": { "200": { "content": { @@ -2734,21 +2731,28 @@ "type": "array", "minItems": 0, "items": { - "$ref": "#/components/schemas/CustomerList.Record" + "$ref": "#/components/schemas/TenantDetails.Record" } }, "examples": { - "Example List Of Customer Records": { - "description": "Sample list of unique customer records in the system", - "summary": "Existing Customer Records", + "Example List Of Tenant Records": { + "description": "Sample list of tenant records in the database", + "summary": "Existing Tenant Records", "value": [ { - "customerId": "5d6e7f8a-9b0c-1d2e-3f4a-5b6c7d8e9f0a", - "customerDisplayName": "Contoso - Legal" + "tenantId": "5d6e7f8a-9b0c-1d2e-3f4a-5b6c7d8e9f0a", + "displayName": "Contoso - Legal", + "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", + "authorizedPrincipalList": [ + "59673771-3b4f-4518-9187-aee8a51c8c07", + "47c42971-2dea-4553-a788-d29a42e3e867" + ] }, { - "customerId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", - "customerDisplayName": "Contoso - R&D" + "tenantId": "7e8f9a0b-1c2d-3e4b-5a6c-7d8e9f0a1b2c", + "displayName": "Contoso - R&D", + "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", + "authorizedPrincipalList": [] } ] } @@ -2756,21 +2760,30 @@ } }, "description": "OK" + }, + "404":{ + "$ref": "#/components/responses/404" + }, + "500": { + "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Retrieves list of customer records", + "summary": "Retrieves list of tenant records", "tags": [ - "Customer Records" + "Tenant Records" ] } }, - "/API/Customer/{customerId}/": { + "/API/Tenant/{tenantId}/": { "get": { - "description": "Retrieves complete details of one customer record including associated list of tenant records. This endpoint requires the `Customer.Read.All` or `Customer.ReadWrite.All` scopes (permissions).", - "operationId": "/API/Customer/:customerId/Get", + "description": "Retrieves details of a specific tenant record. This endpoint requires the `Tenant.Read.All` or `Tenant.ReadWrite.All` scopes (permissions).", + "operationId": "/API/Tenant/:tenantId/Get", "parameters": [ { - "$ref": "#/components/parameters/customerId" + "$ref": "#/components/parameters/tenantId" + }, + { + "$ref": "#/components/parameters/parentId" } ], "responses": { @@ -2778,20 +2791,21 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Customer.Record" + "$ref": "#/components/schemas/TenantDetails.Record" }, "examples": { - "Example Complete Customer Record": { - "description": "Sample details of one customer record with list of associated tenant records", - "summary": "Existing Customer Record", + "Example Complete Tenant Record": { + "description": "Sample details of one tenant record", + "summary": "Existing Tenant Record", "value": { - "customerId": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", - "customerDisplayName": "Contoso - Testing", - "tenantList": { - "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c": "Contoso - Testing", - "2e3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6a7b": "Contoso - Testing - Staging 1", - "4b5c6d7e-8f9a-0b1c-2d3e-4f5a6b7c8d9e": "Contoso - Testing - Staging 2" - } + "tenantId": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", + "displayName": "Contoso - Testing", + "parentId": "f3ed1efc-4e62-46b8-bf2a-6b59ca9784e5", + "authorizedPrincipalList": [ + "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c", + "2e3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6a7b", + "4b5c6d7e-8f9a-0b1c-2d3e-4f5a6b7c8d9e" + ] } } } @@ -2799,26 +2813,21 @@ }, "description": "OK" }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" + "404":{ + "$ref": "#/components/responses/404" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Retrieves Details of One Customer Record", + "summary": "Retrieves Details of One Tenant Record", "tags": [ - "Customer Records" + "Tenant Records" ] - } - }, - "/API/Customer/Tenant/{tenantId}/": { + }, "patch": { - "description": "Update tenant record to either create association with provided customer value, or adjust human readable name, or both. This endpoint requires the `Customer.ReadWrite.All` scope (permission).", - "operationId": "/API/Customer/Tenant/:tenantId/Patch", + "description": "Update tenant record using provided information. Payload could contain any combination of existing properties. This endpoint requires the `Tenant.ReadWrite.All` scopes (permissions).", + "operationId": "/API/Tenant/:tenantId/Patch", "parameters": [ { "$ref": "#/components/parameters/tenantId" @@ -2830,43 +2839,63 @@ "schema": { "type": "object", "properties": { - "customerId": { - "description": "Optional Object ID of the customer record to to use during update process.", - "example": "b2fd105a-2594-437e-b934-1a62a51c28b4", + "displayName": { + "description": "Human readable name for the tenant record", + "type": "string" + }, + "parentId": { + "description": "The object ID of the tenant that is considered a parent to this record", "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" }, - "displayName": { - "description": "Optional string representing human readable name for the records.", - "example": "Contoso - New Tenant", - "type": "string" + "authorizedPrincipalList": { + "description": "List of object IDs that are allowed to access this record and related data.", + "type": "array", + "items": { + "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" + } } - } + }, + "anyOf": [ + { + "required": [ "displayName" ] + }, + { + "required": [ "parentId" ] + }, + { + "required": [ "authorizedPrincipalList" ] + } + ] }, "examples": { - "Example Request for Tenant Association": { - "description": "Sample payload requesting for the referenced tenant record to be associated with provided customer value", - "summary": "Create Customer Association for Tenant", + "Example Request to Update Tenant Parent": { + "description": "Sample payload requesting adjustment to the parent value", + "summary": "Update Parent Information for Tenant", "value": { - "customerId": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d" + "parentId": "6a7b8c9d-0e1f-2a3b-4c5d-6e7f8a9b0c1d" } }, - "Example Request for Tenant Association and Name Update": { - "description": "Sample payload requesting to associate tenant record with the customer value and also update name on the tenant record", - "summary": "Update Tenant Record Name and Create Customer Association for Tenant", + "Example Request for Tenant Name and Parent Update": { + "description": "Sample payload requesting to update parent value and display name on the tenant record", + "summary": "Update Tenant Record Name and Parent Information", "value": { - "customerId": "8f9a0b1c-2d3e-4f5a-6b7c-8d9e0a1b2c3d", + "parentId": "8f9a0b1c-2d3e-4f5a-6b7c-8d9e0a1b2c3d", "displayName": "Contoso - R&D East" } }, - "Example Request for Tenant Name Update": { - "description": "Sample payload requesting to update name on the tenant record", - "summary": "Update Tenant Record Name", + "Example Request for Tenant Authorized Principals Update": { + "description": "Sample payload requesting to update authorized principals for the tenant record", + "summary": "Update Tenant Authorized Principals List", "value": { - "displayName": "Contoso - R&D North" + "authorizedPrincipalList": [ "4cae3355-0cff-410c-b4f9-69cb5de8f1ac", "0e52e6ac-f8e1-4070-ae2e-9bd0a37507a1" ] } } } @@ -2874,20 +2903,29 @@ } }, "responses": { - "204": { - "description": "Updated successfully" - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "404": { - "$ref": "#/components/responses/404" + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TenantDetails.Record" + }, + "examples": { + "Example Complete Tenant Record": { + "description": "Sample response after updating a tenant record", + "summary": "Updated Tenant Record", + "value": { + "tenantId": "c00ffc2c-b6f6-4121-bd8e-4d02e9504eb9", + "displayName": "Contoso - Testing", + "parentId": "8c291062-a4f7-4706-b4df-59e605497f06", + "authorizedPrincipalList": [ + "b856517a-2086-4be4-b63e-d6ca8a5b0ff6" + ] + } + } + } + } + }, + "description": "OK" }, "500": { "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." @@ -2895,7 +2933,7 @@ }, "summary": "Update Tenant Record", "tags": [ - "Customer Records" + "Tenant Records" ] } } From 18bb9320631f25fc545a25beda2297a0c58c8bd6 Mon Sep 17 00:00:00 2001 From: Elliot Huffman Date: Tue, 25 Mar 2025 18:38:47 -0400 Subject: [PATCH 6/6] Wording Fix general wording. Add missing tag description. --- Data-Gateway.json | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/Data-Gateway.json b/Data-Gateway.json index 91fe55b..7431d17 100644 --- a/Data-Gateway.json +++ b/Data-Gateway.json @@ -2768,7 +2768,7 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Retrieves list of tenant records", + "summary": "Retrieves List of Tenant Records", "tags": [ "Tenant Records" ] @@ -2820,13 +2820,13 @@ "description": "Request has a failure that cannot be resolved and might require manual intervention or retry." } }, - "summary": "Retrieves Details of One Tenant Record", + "summary": "Retrieves Tenant Record", "tags": [ "Tenant Records" ] }, "patch": { - "description": "Update tenant record using provided information. Payload could contain any combination of existing properties. This endpoint requires the `Tenant.ReadWrite.All` scopes (permissions).", + "description": "Update tenant record using provided information. Payload could contain any combination of existing properties. To remove a parent, set the parentId to be the same as the tenant ID value. This endpoint requires the `Tenant.ReadWrite.All` scopes (permissions).", "operationId": "/API/Tenant/:tenantId/Patch", "parameters": [ { @@ -2958,6 +2958,10 @@ "url": "https://docs.shilab.com/Date-Gateway/" } }, + { + "description": "Manages the list of tenants that have interacted with the Data Gateway in the past.", + "name": "Tenant Records" + }, { "description": "Collects and reports data from the license analytics product.", "name": "License Analytics",