diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml index e845cfec..2d06d32a 100644 --- a/code/API_definitions/geofencing-subscriptions.yaml +++ b/code/API_definitions/geofencing-subscriptions.yaml @@ -77,7 +77,7 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - x-camara-commonalities: 0.4.0 + x-camara-commonalities: 0.5.0 externalDocs: description: Project documentation at Camara url: https://github.com/camaraproject/DeviceLocation @@ -154,10 +154,10 @@ paths: $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" + "410": + $ref: "#/components/responses/Generic410" + "429": + $ref: "#/components/responses/Generic429" security: - {} - notificationsBearerAuth: [] @@ -190,10 +190,6 @@ paths: $ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422" "429": $ref: "#/components/responses/Generic429" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" get: tags: - Geofencing subscriptions @@ -224,12 +220,6 @@ paths: $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" - "429": - $ref: "#/components/responses/Generic429" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" /subscriptions/{subscriptionId}: get: tags: @@ -261,12 +251,6 @@ paths: $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" - "429": - $ref: "#/components/responses/Generic429" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" delete: tags: - Geofencing subscriptions @@ -302,12 +286,6 @@ paths: $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" - "429": - $ref: "#/components/responses/Generic429" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" components: securitySchemes: openId: @@ -416,7 +394,10 @@ components: description: The subscription expiration time (in date-time format) requested by the API consumer. subscriptionMaxEvents: type: integer - description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. + description: | + Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. + Note on combined usage of `initialEvent` and `subscriptionMaxEvents`: + If an event is triggered following `initialEvent` set to `true`, this event will be counted towards `subscriptionMaxEvents`. minimum: 1 example: 5 initialEvent: @@ -1097,24 +1078,36 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 400 + code: + enum: + - INVALID_ARGUMENT + - INVALID_CREDENTIAL + - INVALID_PROTOCOL + - INVALID_TOKEN examples: - InvalidArgument: + GENERIC_400_INVALID_ARGUMENT: value: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. - InvalidProtocol: + GENERIC_400_INVALID_PROTOCOL: value: status: 400 code: INVALID_PROTOCOL message: Only HTTP is supported. - InvalidCredential: + GENERIC_400_INVALID_CREDENTIAL: value: status: 400 code: INVALID_CREDENTIAL message: Only Access token is supported. - InvalidToken: + GENERIC_400_INVALID_TOKEN: value: status: 400 code: INVALID_TOKEN @@ -1127,11 +1120,54 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: INVALID_ARGUMENT - message: Client specified an invalid argument, request body or query param. + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 400 + code: + enum: + - INVALID_ARGUMENT + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + SubscriptionIdRequired: + description: Problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 400 + code: + enum: + - INVALID_ARGUMENT + examples: + GENERIC_400_INVALID_ARGUMENT: + summary: Schema validation failed + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_SUBSCRIPTION_ID_REQUIRED: + summary: The subscription id is required + value: + status: 400 + code: INVALID_ARGUMENT + message: "Expected property is missing: subscriptionId" Generic401: description: Authentication problem with the client request. headers: @@ -1140,12 +1176,31 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired credentials. - CreateSubscription403: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 401 + code: + enum: + - AUTHENTICATION_REQUIRED + - UNAUTHENTICATED + examples: + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + SubscriptionPermissionDenied403: description: Client does not have sufficient permission. headers: x-correlator: @@ -1153,31 +1208,53 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 403 + code: + enum: + - PERMISSION_DENIED + - SUBSCRIPTION_MISMATCH examples: - PermissionDenied: + GENERIC_403_PERMISSION_DENIED: value: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. - TokenMismatch: + GENERIC_403_TOKEN_MISMATCH: value: status: 403 code: SUBSCRIPTION_MISMATCH message: Inconsistent access token for requested events subscription. Generic403: - description: Forbidden + description: Client does not have sufficient permission headers: x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: PERMISSION_DENIED - message: Client does not have sufficient permissions to perform this action. + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 403 + code: + enum: + - PERMISSION_DENIED + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. Generic404: description: Not found headers: @@ -1186,7 +1263,16 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 404 + code: + enum: + - NOT_FOUND examples: GENERIC_404_NOT_FOUND: description: Resource is not found @@ -1194,6 +1280,32 @@ components: status: 404 code: NOT_FOUND message: The specified resource is not found. + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 410 + code: + enum: + - GONE + examples: + GENERIC_410_GONE: + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + value: + status: 410 + code: GONE + message: + Access to the target resource is no longer available. CreateSubscriptionUnprocessableEntity422: description: Unprocessable Entity headers: @@ -1202,30 +1314,56 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 422 + code: + enum: + - AREA_NOT_COVERED + - IDENTIFIER_MISMATCH + - MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED + - SERVICE_NOT_APPLICABLE + - UNNECESSARY_IDENTIFIER + - UNSUPPORTED_IDENTIFIER examples: - MultieventSubscriptionNotSupported: + GENERIC_422_AREA_NOT_COVERED: value: status: 422 - code: MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED - message: Multi event types subscription not managed. - DeviceIdentifierMismatch: + code: AREA_NOT_COVERED + message: The specified area cannot be covered or is too small to be valid + GENERIC_422_IDENTIFIER_MISMATCH: description: Inconsistency between device identifiers not pointing to the same device. value: status: 422 - code: DEVICE_IDENTIFIERS_MISMATCH - message: Provided device identifiers are not consistent. - DeviceNotApplicable: - description: Service is not available for the provided device. + code: IDENTIFIER_MISMATCH + message: Provided identifiers are not consistent. + GENERIC_422_SERVICE_NOT_APPLICABLE: + description: Service not applicable for the provided identifier + value: + status: 422 + code: SERVICE_NOT_APPLICABLE + message: The service is not available for the provided identifier. + GENERIC_422_MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED: + value: + status: 422 + code: MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED + message: Multi event types subscription not managed. + GENERIC_422_UNNECESSARY_IDENTIFIER: + description: An explicit identifier is provided when a device or phone number has already been identified from the access token value: status: 422 - code: DEVICE_NOT_APPLICABLE - message: The service is not available for the provided device. - AreaNotCovered: + code: UNNECESSARY_IDENTIFIER + message: The device is already identified by the access token. + GENERIC_422_UNSUPPORTED_IDENTIFIER: + description: None of the provided identifiers is supported by the implementation value: status: 422 - code: "AREA_NOT_COVERED" - message: "The specified area cannot be covered or is too small to be valid" + code: UNSUPPORTED_IDENTIFIER + message: The identifier provided is not supported. Generic429: description: Too Many Requests headers: @@ -1234,7 +1372,17 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 429 + code: + enum: + - QUOTA_EXCEEDED + - TOO_MANY_REQUESTS examples: GENERIC_429_QUOTA_EXCEEDED: description: Request is rejected due to exceeding a business quota limit. @@ -1248,58 +1396,6 @@ components: status: 429 code: TOO_MANY_REQUESTS message: Either out of resource quota or reaching rate limiting. - - Generic500: - description: Server error. - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: INTERNAL - message: Server error - Generic503: - description: Service unavailable. Typically the server is down. - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - GENERIC_503_UNAVAILABLE: - description: Service is not available. Temporary situation usually related to maintenance process in the server side. - value: - status: 503 - code: UNAVAILABLE - message: Service Unavailable. - SubscriptionIdRequired: - description: Problem with the client request - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - Generic400: - summary: Schema validation failed - value: - status: 400 - code: INVALID_ARGUMENT - message: "Client specified an invalid argument, request body or query param" - subscriptionIdRequired: - summary: subscription id is required - value: - status: 400 - code: INVALID_ARGUMENT - message: "Expected property is missing: subscriptionId" examples: REQUEST_CIRCLE_AREA_ENTERED: description: A sample geofence for entering for a circle area.