diff --git a/code/API_definitions/device-data-volume.yaml b/code/API_definitions/device-data-volume.yaml index f9661ce..d950eff 100644 --- a/code/API_definitions/device-data-volume.yaml +++ b/code/API_definitions/device-data-volume.yaml @@ -99,11 +99,16 @@ paths: - openId: - device-data-volume:read requestBody: + required: true content: application/json: schema: $ref: "#/components/schemas/RetrieveDataVolumeRequest" - required: true + examples: + Retrieve Request: + $ref: "#/components/examples/RetrieveRequest" + Retrieve Request With 2-legged Access Token: + $ref: "#/components/examples/RetrieveRequestWith2-leggedAccessToken" responses: "200": description: Contains information about the remaining device data volume. @@ -117,6 +122,8 @@ paths: examples: Successful Response: $ref: "#/components/examples/SuccessfulRetrieveResponse" + Successful Retrieve Response With Unknown Status Time: + $ref: "#/components/examples/SuccessfulRetrieveResponseWithUnknownStatusTime" Successful Response With Device Disambiguation: $ref: "#/components/examples/SuccessfulRetrieveResponseWithDeviceDisambiguation" "400": @@ -145,11 +152,16 @@ paths: - openId: - device-data-volume:read requestBody: + required: true content: application/json: schema: $ref: "#/components/schemas/CheckDataVolumeRequest" - required: true + examples: + Check Request: + $ref: "#/components/examples/CheckRequest" + Retrieve Request With 2-legged Access Token: + $ref: "#/components/examples/CheckRequestWith2-leggedAccessToken" responses: "200": description: Boolean response indicating if the remaining data volume exceeds the provided threshold @@ -163,6 +175,8 @@ paths: examples: Successful Response: $ref: "#/components/examples/SuccessfulCheckResponse" + Successful Check Response With Unknown Status Time: + $ref: "#/components/examples/SuccessfulCheckResponseWithUnknownStatusTime" Successful Response With Device Disambiguation: $ref: "#/components/examples/SuccessfulCheckResponseWithDeviceDisambiguation" "400": @@ -184,6 +198,16 @@ components: $ref: "../common/CAMARA_common.yaml#/components/securitySchemes/openId" schemas: + LastStatusTime: + description: | + The last time that the device data volume status was confirmed to be correct by the API provider. It might not be possible to provide the current status because, for example, the device may not be connected to any mobile network. + It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + type: string + format: date-time + maxLength: 64 + 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. type: string @@ -230,14 +254,17 @@ components: CheckDataVolumeResponse: description: Represents the response, if the data volume exceeds a given threshold. type: object + required: + - lastStatusTime + - thresholdExceeded properties: device: $ref: "../common/CAMARA_common.yaml#/components/schemas/DeviceResponse" + lastStatusTime: + $ref: "#/components/schemas/LastStatusTime" thresholdExceeded: type: boolean description: Indicates whether the remaining data volume exceeds the given threshold - required: - - thresholdExceeded RetrieveDataVolumeRequest: description: | @@ -251,32 +278,71 @@ components: RetrieveDataVolumeResponse: description: Represents the remaining data volume of the requested device. type: object + required: + - lastStatusTime + - dataVolumeCategory properties: device: $ref: "../common/CAMARA_common.yaml#/components/schemas/DeviceResponse" + lastStatusTime: + $ref: "#/components/schemas/LastStatusTime" dataVolumeCategory: $ref: "#/components/schemas/DataVolumeCategory" - required: - - dataVolumeCategory examples: + RetrieveRequest: + description: Request device data volume category with 3-legged access token + value: {} + RetrieveRequestWith2-leggedAccessToken: + description: Request device data volume category with 2-legged access token + value: + device: + phoneNumber: "+123456789" SuccessfulRetrieveResponse: - description: Successfully retrieve the device data volume category + description: Successfully retrieve the device data volume category with known status time value: + lastStatusTime: "2024-02-20T10:41:38.657Z" + dataVolumeCategory: "<200MiB" + SuccessfulRetrieveResponseWithUnknownStatusTime: + description: Successfully retrieve the device data volume category, but status time of that information is unknown + value: + lastStatusTime: null dataVolumeCategory: "<200MiB" SuccessfulRetrieveResponseWithDeviceDisambiguation: description: Successfully retrieve the device data volume category but device disambiguation is required value: device: phoneNumber: "+123456789" + lastStatusTime: "2024-02-20T10:41:38.657Z" dataVolumeCategory: "<200MiB" + CheckRequest: + description: Request device data volume category check with 3-legged access token + value: + volumeToCheck: + value: 500 + unit: "MiB" + CheckRequestWith2-leggedAccessToken: + description: Request device data volume category check with 2-legged access token + value: + device: + phoneNumber: "+123456789" + volumeToCheck: + value: 500 + unit: "MiB" SuccessfulCheckResponse: - description: Successfully check the device data volume category + description: Successfully check the device data volume category 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 value: + lastStatusTime: null thresholdExceeded: false SuccessfulCheckResponseWithDeviceDisambiguation: description: Successfully check the device data volume category but device disambiguation is required value: device: phoneNumber: "+123456789" + lastStatusTime: "2024-02-20T10:41:38.657Z" thresholdExceeded: true