From 5b8727fd704733aebec9a0d7018944decc5ce8f8 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 21 Aug 2026 10:30:50 +0100 Subject: [PATCH 1/5] Refactor data volume API definitions for allowances Updated data volume definitions to use data allowance units and adjusted related properties. --- code/API_definitions/device-data-volume.yaml | 107 ++++++++++--------- 1 file changed, 57 insertions(+), 50 deletions(-) diff --git a/code/API_definitions/device-data-volume.yaml b/code/API_definitions/device-data-volume.yaml index d950eff..761f583 100644 --- a/code/API_definitions/device-data-volume.yaml +++ b/code/API_definitions/device-data-volume.yaml @@ -208,48 +208,48 @@ components: nullable: true example: "2018-04-05T17:31:00Z" - VolumeUnitEnum: - description: Enumeration of volume units, where "MiB" is 2^20 bytes and "GiB" is 2^30 bytes. + DataAllowanceUnit: + description: The units used to express the data allowance, where "MB" is 10^6 bytes and "GB" is 10^9 bytes. Note that these definitions may be different to the definitions used by the mobile network operator for data allowances, but the API consumer will perform any required unit conversion. type: string enum: - - MiB - - GiB + - MB + - GB - DataVolumeCategory: - description: Estimated remaining data volume category, where "MiB" is 2^20 bytes and "GiB" is 2^30 bytes. - type: string - enum: - - "<200MiB" - - "<1GiB" - - "<5GiB" - - ">=5GiB" + DataAllowance: + description: The size of the data allowance, expressed as a quantity of data allowance units + type: object + required: + - value + - unit + properties: + value: + description: Quantity of the data allowance + type: integer + format: int32 + minimum: 0 + maximum: 1000 + example: 500 + unit: + description: The units used to express the data allowance, where "MB" is 10^6 bytes and "GB" is 10^9 bytes. Note that these definitions may be different to the definitions used by the mobile network operator for data allowances, but the API consumer will perform any required unit conversion. + type: string + enum: + - MB + - GB CheckDataVolumeRequest: description: | The request to check, if the current remaining data volume is above the requested threshold. Device is not required when using a 3-legged access token, following the rules in the description. type: object + required: + - dataAllowanceThreshold properties: device: $ref: "../common/CAMARA_common.yaml#/components/schemas/Device" - volumeToCheck: - type: object - description: Volume threshold to check against - properties: - value: - description: Quantity of volume to check - type: integer - example: 500 - format: int32 - minimum: 0 - maximum: 1024 - unit: - $ref: "#/components/schemas/VolumeUnitEnum" - required: - - value - - unit - required: - - volumeToCheck + dataAllowanceThreshold: + description: The data allowance threshold to check against + allOf: + - $ref: #/components/schemas/DataAllowance CheckDataVolumeResponse: description: Represents the response, if the data volume exceeds a given threshold. @@ -280,67 +280,74 @@ components: type: object required: - lastStatusTime - - dataVolumeCategory + - dataAllowance properties: device: $ref: "../common/CAMARA_common.yaml#/components/schemas/DeviceResponse" lastStatusTime: $ref: "#/components/schemas/LastStatusTime" - dataVolumeCategory: - $ref: "#/components/schemas/DataVolumeCategory" + dataAllowance: + oneOf: + - $ref: "#/components/schemas/DataAllowance" + - type: string + enum: "Unlimited" examples: RetrieveRequest: - description: Request device data volume category with 3-legged access token + description: Request remaining device data allowance using a 3-legged access token value: {} RetrieveRequestWith2-leggedAccessToken: - description: Request device data volume category with 2-legged access token + description: Request remaining device data allowance using a 2-legged access token value: device: phoneNumber: "+123456789" SuccessfulRetrieveResponse: - description: Successfully retrieve the device data volume category with known status time + description: Successfully retrieve the remaining device data allowance with known status time value: lastStatusTime: "2024-02-20T10:41:38.657Z" - dataVolumeCategory: "<200MiB" + dataAllowance: Unlimited SuccessfulRetrieveResponseWithUnknownStatusTime: - description: Successfully retrieve the device data volume category, but status time of that information is unknown + description: Successfully retrieve the remaining device data allowance, but status time of that information is unknown value: lastStatusTime: null - dataVolumeCategory: "<200MiB" + dataAllowance: + value: 1000 + unit: GB SuccessfulRetrieveResponseWithDeviceDisambiguation: - description: Successfully retrieve the device data volume category but device disambiguation is required + description: Successfully retrieve the remaining device data allowance, but device disambiguation is required value: device: phoneNumber: "+123456789" lastStatusTime: "2024-02-20T10:41:38.657Z" - dataVolumeCategory: "<200MiB" + dataAllowance: + value: 200 + unit: MB CheckRequest: - description: Request device data volume category check with 3-legged access token + description: Request remaining device data allowance check using a 3-legged access token value: - volumeToCheck: + dataAllowanceThreshold: value: 500 - unit: "MiB" + unit: "MB" CheckRequestWith2-leggedAccessToken: - description: Request device data volume category check with 2-legged access token + description: Request remaining device data allowance check using a 2-legged access token value: device: phoneNumber: "+123456789" - volumeToCheck: + dataAllowanceThreshold: value: 500 - unit: "MiB" + unit: "MB" SuccessfulCheckResponse: - description: Successfully check the device data volume category with known status time + description: Successfully check the remaining device data allowance with known status time value: lastStatusTime: "2024-02-20T10:41:38.657Z" thresholdExceeded: false SuccessfulCheckResponseWithUnknownStatusTime: - description: Successfully check the device data volume category, but status time of that information is unknown + description: Successfully check the remaining device data allowance, but status time of that information is unknown value: lastStatusTime: null thresholdExceeded: false SuccessfulCheckResponseWithDeviceDisambiguation: - description: Successfully check the device data volume category but device disambiguation is required + description: Successfully check the remaining device data allowance, but device disambiguation is required value: device: phoneNumber: "+123456789" From c036ebf4a78dd0b4be9e257050132af5699e83d5 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 21 Aug 2026 10:33:42 +0100 Subject: [PATCH 2/5] Refactor device-data-volume.yaml by removing DataAllowanceUnit Removed DataAllowanceUnit schema and updated enum for dataAllowance. --- code/API_definitions/device-data-volume.yaml | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/code/API_definitions/device-data-volume.yaml b/code/API_definitions/device-data-volume.yaml index 761f583..d2f35f9 100644 --- a/code/API_definitions/device-data-volume.yaml +++ b/code/API_definitions/device-data-volume.yaml @@ -208,13 +208,6 @@ components: nullable: true example: "2018-04-05T17:31:00Z" - DataAllowanceUnit: - description: The units used to express the data allowance, where "MB" is 10^6 bytes and "GB" is 10^9 bytes. Note that these definitions may be different to the definitions used by the mobile network operator for data allowances, but the API consumer will perform any required unit conversion. - type: string - enum: - - MB - - GB - DataAllowance: description: The size of the data allowance, expressed as a quantity of data allowance units type: object @@ -290,7 +283,8 @@ components: oneOf: - $ref: "#/components/schemas/DataAllowance" - type: string - enum: "Unlimited" + enum: + - Unlimited examples: RetrieveRequest: From 0fc926e8357e60df3ce289d734a08a70e9d544f8 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 21 Aug 2026 10:46:29 +0100 Subject: [PATCH 3/5] Fix YAML references and update data allowance descriptions --- code/API_definitions/device-data-volume.yaml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/device-data-volume.yaml b/code/API_definitions/device-data-volume.yaml index d2f35f9..7648ffe 100644 --- a/code/API_definitions/device-data-volume.yaml +++ b/code/API_definitions/device-data-volume.yaml @@ -242,7 +242,7 @@ components: dataAllowanceThreshold: description: The data allowance threshold to check against allOf: - - $ref: #/components/schemas/DataAllowance + - $ref: "#/components/schemas/DataAllowance" CheckDataVolumeResponse: description: Represents the response, if the data volume exceeds a given threshold. @@ -280,9 +280,11 @@ components: lastStatusTime: $ref: "#/components/schemas/LastStatusTime" dataAllowance: + description: The data allowance remaining oneOf: - $ref: "#/components/schemas/DataAllowance" - type: string + description: Possible data allowance values not expressed as specific values enum: - Unlimited @@ -299,14 +301,14 @@ components: description: Successfully retrieve the remaining device data allowance with known status time value: lastStatusTime: "2024-02-20T10:41:38.657Z" - dataAllowance: Unlimited + dataAllowance: "Unlimited" SuccessfulRetrieveResponseWithUnknownStatusTime: description: Successfully retrieve the remaining device data allowance, but status time of that information is unknown value: lastStatusTime: null dataAllowance: value: 1000 - unit: GB + unit: "GB" SuccessfulRetrieveResponseWithDeviceDisambiguation: description: Successfully retrieve the remaining device data allowance, but device disambiguation is required value: @@ -315,7 +317,7 @@ components: lastStatusTime: "2024-02-20T10:41:38.657Z" dataAllowance: value: 200 - unit: MB + unit: "MB" CheckRequest: description: Request remaining device data allowance check using a 3-legged access token value: From 0e2d6b2860a8598f147ac3ebeb505c545c12e020 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 21 Aug 2026 11:39:47 +0100 Subject: [PATCH 4/5] Update data volume feature to check dataAllowance --- .../device-data-volume-retrieveDataVolume.feature | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/Test_definitions/device-data-volume-retrieveDataVolume.feature b/code/Test_definitions/device-data-volume-retrieveDataVolume.feature index 5aed7f8..36bfc01 100644 --- a/code/Test_definitions/device-data-volume-retrieveDataVolume.feature +++ b/code/Test_definitions/device-data-volume-retrieveDataVolume.feature @@ -32,7 +32,7 @@ Feature: CAMARA Device Data Volume API, vwip - Operation retrieveDataVolume And the response header "Content-Type" is "application/json" And the response header "x-correlator" has same value as the request header "x-correlator" And the response body complies with the OAS schema at "#/components/schemas/RetrieveDataVolumeResponse" - And the response body property "$.dataVolumeCategory" is present and has value "<200MiB", "<1GiB", "<5GiB", or ">=5GiB" + And the response body property "$.dataAllowance" is present and complies either with the OAS schema at "#/components/schemas/DataAllowance", or equals "Unlimited" And the response body property "$.lastStatusTime" is present and either has a valid date-time format for a time in the past, or is null ################# From 1cae9233bdec7fc7df3683cf1862ea3f3ee4466a Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 21 Aug 2026 11:45:51 +0100 Subject: [PATCH 5/5] Rename dataAllowance to remainingDataAllowance --- code/API_definitions/device-data-volume.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/device-data-volume.yaml b/code/API_definitions/device-data-volume.yaml index 19a64db..d9e2da0 100644 --- a/code/API_definitions/device-data-volume.yaml +++ b/code/API_definitions/device-data-volume.yaml @@ -277,13 +277,13 @@ components: type: object required: - lastStatusTime - - dataAllowance + - remainingDataAllowance properties: device: $ref: "../common/CAMARA_common.yaml#/components/schemas/DeviceResponse" lastStatusTime: $ref: "#/components/schemas/LastStatusTime" - dataAllowance: + remainingDataAllowance: description: The data allowance remaining oneOf: - $ref: "#/components/schemas/DataAllowance" @@ -305,12 +305,12 @@ components: description: Successfully retrieve the remaining device data allowance with known status time value: lastStatusTime: "2024-02-20T10:41:38.657Z" - dataAllowance: "Unlimited" + remainingDataAllowance: "Unlimited" SuccessfulRetrieveResponseWithUnknownStatusTime: description: Successfully retrieve the remaining device data allowance, but status time of that information is unknown value: lastStatusTime: null - dataAllowance: + remainingDataAllowance: value: 1000 unit: "GB" SuccessfulRetrieveResponseWithDeviceDisambiguation: @@ -319,7 +319,7 @@ components: device: phoneNumber: "+123456789" lastStatusTime: "2024-02-20T10:41:38.657Z" - dataAllowance: + remainingDataAllowance: value: 200 unit: "MB" CheckRequest: