Merge branch 'main' into jgarciahospital-patch-5

code/API_definitions/population-density-data.yaml

@@ -92,6 +92,9 @@ info:
     properties too big for both synchronous and asynchronous processing, the API
     returns the error response `POPULATION_DENSITY_DATA.UNSUPPPORTED_REQUEST`.
 
+    If an error happens during the asynchronous processing of the request. The API callback
+    will have property `status` with value `OPERATION_NOT_COMPLETED` as an error cannot be returned in the callback.
+    The callback will also include the `statusInfo` property to add extra information about the error.
 
     **NOTE**: In order to ensure anonymized information, if the data relating to
     a grid cell in the required time interval is not sufficient to be exposed due
@@ -200,6 +203,8 @@ paths:
                         $ref: '#/components/examples/PopulationDensityAreaNotSupportedAsyncResponseExample'
                       PopulationDensityPartOfAreaNotSupportedAsyncResponseExample:
                         $ref: '#/components/examples/PopulationDensityPartOfAreaNotSupportedAsyncResponseExample'
+                      PopulationDensityOperationNotCompletedExample:
+                        $ref: '#/components/examples/PopulationDensityOperationNotCompletedExample'
               responses:
                 '204':
                   description: Successful notification
@@ -256,6 +261,8 @@ paths:
           $ref: '#/components/responses/Generic403'
         '404':
           $ref: '#/components/responses/Generic404'
+        '422':
+          $ref: '#/components/responses/RetrieveLocationUnprocessableContent422'
         '500':
           $ref: '#/components/responses/Generic500'
         '503':
@@ -499,6 +506,10 @@ components:
             $ref: '#/components/schemas/TimedPopulationDensityData'
         status:
           $ref: '#/components/schemas/ResponseStatus'
+        statusInfo:
+          type: string
+          description: Information about the status, mandatory when property `status` is `OPERATION_NOT_COMPLETED` for adding extra information about the error.
+          example: Some error happened during the processing of the request
       required:
         - timedPopulationDensityData
         - status
@@ -529,10 +540,13 @@ components:
           - `PART_OF_AREA_NOT_SUPPORTED`: Part of the requested area is outside the MNOs coverage area, the cells outside the coverage
           area will have property `dataType` with value `NO_DATA`.
           - `AREA_NOT_SUPPORTED`: The whole requested area is outside the MNOs coverage area. No data will be returned.
+          - `OPERATION_NOT_COMPLETED`: An error happened during asynchronous processing of the request. This status will only be returned
+          in case the asynchronous API behaviour is used.
       enum:
         - SUPPORTED_AREA
         - PART_OF_AREA_NOT_SUPPORTED
         - AREA_NOT_SUPPORTED
+        - OPERATION_NOT_COMPLETED
     TimedPopulationDensityData:
       type: object
       properties:
@@ -641,13 +655,10 @@ components:
         Problem with the client request. In addition to generic scenarios of
         `INVALID_ARGUMENT`, `INVALID_CREDENTIAL`, `INVALID_TOKEN`, another scenarios may exist:
           - The area is not a polygon shape or exceeds supported complexity ("code": "POPULATION_DENSITY_DATA.INVALID_AREA", "message": "The area is not a polygon shape or exceeds supported complexity")
-          - Indicated combination of area, time interval and precision is too big ("code": "POPULATION_DENSITY_DATA.UNSUPPPORTED_REQUEST", "message": "Indicated combination of area, time interval and precision is too big")
           - Indicated `startTime` is greater than the maximum allowed ("code": "POPULATION_DENSITY_DATA.MAX_STARTTIME_EXCEEDED", "message": "Indicated startTime is greater than the maximum allowed")
           - Indicated `startTime` is earlier than the minimum allowed ("code": "POPULATION_DENSITY_DATA.MIN_STARTTIME_EXCEEDED", "message": "Indicated startTime is earlier than the minimum allowed")
           - Indicated `endTime` is earlier than the `startTime` ("code": "POPULATION_DENSITY_DATA.INVALID_END_DATE", "message": "Indicated endTime is earlier than the startTime")
           - Indicated time period is greater than the maximum allowed (More than maximum hours between startTime and endTime) ("code": "POPULATION_DENSITY_DATA.MAX_TIME_PERIOD_EXCEEDED", "message": "Indicated time period is greater than the maximum allowed (More than maximum hours between startTime and endTime)")
-          - Indicated cell precision (Geohash level) is not supported ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION", "message": "Indicated cell precision (Geohash level) is not supported")
-          - Indicated combination of area, time interval and precision is too big for a sync response ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE", "message": "Indicated combination of area, time interval and precision is too big for a sync response")
       headers:
         x-correlator:
           $ref: '#/components/headers/x-correlator'
@@ -676,11 +687,6 @@ components:
                 status: 400
                 code: POPULATION_DENSITY_DATA.INVALID_AREA
                 message: The area is not a polygon shape or has an arbitrary complexity
-            UnsupportedRequestIssue:
-              value:
-                status: 400
-                code: POPULATION_DENSITY_DATA.UNSUPPPORTED_REQUEST
-                message: Indicated combination of area, time interval and precision is too big
             MaxStartTimeIssue:
               value:
                 status: 400
@@ -705,18 +711,6 @@ components:
                 message: >-
                   Indicated time period is greater than the maximum allowed
                   (More than maximum hours between startTime and endTime)
-            PrecisionNotSupportedIssue:
-              value:
-                status: 400
-                code: POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION
-                message: >-
-                  Indicated cell precision (Geohash length) is not supported
-            UnsupportedSyncResponseIssue:
-              value:
-                status: 400
-                code: POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE
-                message: >-
-                  Indicated combination of area, time interval and precision is too big for a sync response
     Generic400:
       description: Problem with the client request
       headers:
@@ -785,6 +779,37 @@ components:
                 status: 410
                 code: GONE
                 message: Access to the target resource is no longer available.
+    RetrieveLocationUnprocessableContent422:
+      description: >-
+        Problem with the client request. The following scenarios may exist:
+          - Indicated combination of area, time interval and precision is too big ("code": "POPULATION_DENSITY_DATA.UNSUPPPORTED_REQUEST", "message": "Indicated combination of area, time interval and precision is too big")
+          - Indicated cell precision (Geohash level) is not supported ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION", "message": "Indicated cell precision (Geohash level) is not supported")
+          - Indicated combination of area, time interval and precision is too big for a sync response ("code": "POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE", "message": "Indicated combination of area, time interval and precision is too big for a sync response")
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorInfo'
+          examples:
+            UnsupportedRequestIssue:
+              value:
+                status: 422
+                code: POPULATION_DENSITY_DATA.UNSUPPPORTED_REQUEST
+                message: Indicated combination of area, time interval and precision is too big
+            PrecisionNotSupportedIssue:
+              value:
+                status: 422
+                code: POPULATION_DENSITY_DATA.UNSUPPORTED_PRECISION
+                message: >-
+                  Indicated cell precision (Geohash length) is not supported
+            UnsupportedSyncResponseIssue:
+              value:
+                status: 422
+                code: POPULATION_DENSITY_DATA.UNSUPPORTED_SYNC_RESPONSE
+                message: >-
+                  Indicated combination of area, time interval and precision is too big for a sync response
     Generic500:
       description: Internal server error
       headers:
@@ -965,3 +990,8 @@ components:
         status: AREA_NOT_SUPPORTED
         timedPopulationDensityData: []
         operationId: 2322f362-eaab-4cf3-86d2-efcbdf3a7cb4
+    PopulationDensityOperationNotCompletedExample:
+      value:
+        status: OPERATION_NOT_COMPLETED
+        timedPopulationDensityData: []
+        statusInfo: Some error happened during the processing of the request