diff --git a/code/API_definitions/sim-swap-notification-subscription.yaml b/code/API_definitions/sim-swap-notification-subscription.yaml index e0a0600..b7315e4 100644 --- a/code/API_definitions/sim-swap-notification-subscription.yaml +++ b/code/API_definitions/sim-swap-notification-subscription.yaml @@ -27,15 +27,16 @@ info: It is mandatory in the subscription to provide the event `types` subscribed are several are managed in this API. Only one event ``types`` is managed for this API: - - ``org.camaraproject.sim-swap.v0.swapped`` - Event triggered when a sim swap occurs on the associated phoneNumber + - ``org.camaraproject.sim-swap-subscriptions.v0.swapped`` - Event triggered when a sim swap occurs on the associated phoneNumber - Note: Additionally to these list, ``org.camaraproject.sim-swap.v0.subscription-ends`` notification `types` is sent when the subscription ends. + Note: Additionally to these list, ``org.camaraproject.sim-swap-subscriptions.v0.subscription-ends`` notification `types` is sent when the subscription ends. This notification does not require dedicated subscription. It is used when: - the subscription expire time (optionally set by the requester) has been reached - the maximum number of subscription events (optionally set by the requester) has been reached - the API server has to stop sending notification prematurely + - the Access Token sinkCredential (optionally set by the requester) expiration time has been reached ### Notification callback @@ -66,7 +67,7 @@ externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/ servers: - - url: '{apiRoot}/sim-swap-notification-subscriptions/v0' + - url: '{apiRoot}/sim-swap-subscriptions/v0' variables: apiRoot: default: http://localhost:9091 @@ -87,12 +88,15 @@ paths: - $ref: "#/components/parameters/x-correlator" security: - openId: - - sim-swap-notification-subscriptions:org.camaraproject.sim-swap.v0.swapped:read + - sim-swap-subscriptions:org.camaraproject.sim-swap-subscriptions.v0.swapped:read requestBody: content: application/json: schema: $ref: "#/components/schemas/SubscriptionRequest" + examples: + SUBSCRIPTION_REQUEST: + $ref: '#/components/examples/SUBSCRIPTION_REQUEST' required: true callbacks: notifications: @@ -108,7 +112,7 @@ paths: requestBody: required: true content: - application/json: + application/cloudevents+json: schema: $ref: "#/components/schemas/CloudEvent" examples: @@ -150,6 +154,9 @@ paths: application/json: schema: $ref: "#/components/schemas/Subscription" + examples: + SUBSCRIPTION_RESPONSE: + $ref: '#/components/examples/SUBSCRIPTION_RESPONSE' "202": description: Request accepted to be processed. It applies for async creation process. headers: @@ -187,7 +194,7 @@ paths: - $ref: "#/components/parameters/x-correlator" security: - openId: - - sim-swap-notification-subscriptions:read + - sim-swap-subscriptions:read responses: "200": description: List of event subscription details @@ -201,6 +208,10 @@ paths: minItems: 0 items: $ref: '#/components/schemas/Subscription' + examples: + SUBSCRIPTIONS: + $ref: '#/components/examples/SUBSCRIPTIONS' + "400": $ref: "#/components/responses/Generic400" "401": @@ -220,7 +231,7 @@ paths: operationId: retrieveSubscription security: - openId: - - sim-swap-notification-subscriptions:read + - sim-swap-subscriptions:read parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: "#/components/parameters/x-correlator" @@ -234,6 +245,9 @@ paths: application/json: schema: $ref: "#/components/schemas/Subscription" + examples: + SUBSCRIPTION: + $ref: '#/components/examples/SUBSCRIPTION_RESPONSE' "400": $ref: "#/components/responses/SubscriptionIdRequired" "401": @@ -254,13 +268,13 @@ paths: description: delete a given event subscription. security: - openId: - - sim-swap-notification-subscriptions::delete + - sim-swap-subscriptions:delete parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: "#/components/parameters/x-correlator" responses: "204": - description: im swap notification subscription deleted + description: Sim swap notification subscription deleted headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -355,12 +369,12 @@ components: types: description: | Camara Event types eligible for subscription: - - org.camaraproject.sim-swap.v0.swapped: receive a notification when a sim swap is performed on the line. + - org.camaraproject.sim-swap-subscriptions.v0.swapped: receive a notification when a sim swap is performed on the line. Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided at API project level. type: array example: - - "org.camaraproject.sim-swap.v0.swapped" + - "org.camaraproject.sim-swap-subscriptions.v0.swapped" items: type: string config: @@ -518,8 +532,8 @@ components: subscription-ends: Event triggered when the subscription ends enum: - - org.camaraproject.sim-swap.v0.swapped - - org.camaraproject.sim-swap.v0.subscription-ends + - org.camaraproject.sim-swap-subscriptions.v0.swapped + - org.camaraproject.sim-swap-subscriptions.v0.subscription-ends Subscription: description: Represents a event-type subscription. @@ -544,7 +558,7 @@ components: types: description: | Camara Event types eligible for subscription: - - org.camaraproject.sim-swap.v0.swapped: receive a notification when a sim swap is performed on the line. + - org.camaraproject.sim-swap-subscriptions.v0.swapped: receive a notification when a sim swap is performed on the line. Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided at API project level. type: array @@ -635,8 +649,8 @@ components: discriminator: propertyName: "type" mapping: - org.camaraproject.sim-swap.v0.swapped: '#/components/schemas/EventSimSwap' - org.camaraproject.sim-swap.v0.subscription-ends: '#/components/schemas/EventSubscriptionEnds' + org.camaraproject.sim-swap-subscriptions.v0.swapped: '#/components/schemas/EventSimSwap' + org.camaraproject.sim-swap-subscriptions.v0.subscription-ends: '#/components/schemas/EventSubscriptionEnds' Source: type: string @@ -707,10 +721,12 @@ components: - NETWORK_TERMINATED - API server stopped sending notification - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the requester) has been reached + - ACCESS_TOKEN_EXPIRED - Access Token sinkCredential (optionally set by the requester) expiration time has been reached enum: - MAX_EVENTS_REACHED - NETWORK_TERMINATED - SUBSCRIPTION_EXPIRED + - ACCESS_TOKEN_EXPIRED HTTPSubscriptionRequest: allOf: @@ -939,7 +955,7 @@ components: TokenMismatch: value: status: 403 - code: "SUSBCRIPTION_MISMATCH" + code: "SUBSCRIPTION_MISMATCH" message: "Inconsistent access token for requested events subscription" Generic403: description: Client does not have sufficient permission @@ -1088,7 +1104,7 @@ components: value: id: "123655" source: supertelco.notificationSendServer12 - type: org.camaraproject.sim-swap.v0.swapped + type: org.camaraproject.sim-swap-subscriptions.v0.swapped specversion: "1.0" datacontenttype: application/json data: @@ -1100,7 +1116,7 @@ components: value: id: "123658" source: supertelco.notificationSendServer12 - type: org.camaraproject.sim-swap.v0.subscription-ends + type: org.camaraproject.sim-swap-subscriptions.v0.subscription-ends specversion: "1.0" datacontenttype: application/json data: @@ -1109,3 +1125,62 @@ components: subscriptionId: 2ghy-55gg-7iup-yuo9 terminationDescription: subscription expire time reached time: 2023-01-19T13:18:23.682Z + + SUBSCRIPTION_REQUEST: + value: + protocol: HTTP + sink: https://endpoint.example.com/sink + sinkCredential: + credentialType: ACCESSTOKEN + accessToken: "yJ2ZXIiOiIxLjAiLCJ0eXAiO..." + accessTokenExpiresUtc: "1717753038" + accessTokenType: "bearer" + types: + - org.camaraproject.sim-swap-subscriptions.v0.swapped + config: + subscriptionDetail: + phoneNumber: "+123456789" + subscriptionExpireTime: '2025-01-17T13:18:23.682Z' + subscriptionMaxEvents: 5 + + SUBSCRIPTION_RESPONSE: + value: + protocol: HTTP + sink: https://endpoint.example.com/sink + sinkCredential: + credentialType: ACCESSTOKEN + accessToken: "yJ2ZXIiOiIxLjAiLCJ0eXAiO..." + accessTokenExpiresUtc: "1717753038" + accessTokenType: "bearer" + types: + - org.camaraproject.sim-swap-subscriptions.v0.swapped + config: + subscriptionDetail: + phoneNumber: "+123456789" + subscriptionExpireTime: '2025-01-17T13:18:23.682Z' + subscriptionMaxEvents: 5 + id: '1119920371' + startsAt: '2024-06-07T16:10:15.302Z' + expiresAt: '2024-06-07T16:10:15.302Z' + status: ACTIVATION_REQUESTED + + SUBSCRIPTIONS: + value: + - protocol: HTTP + sink: https://endpoint.example.com/sink + sinkCredential: + credentialType: ACCESSTOKEN + accessToken: "yJ2ZXIiOiIxLjAiLCJ0eXAiO..." + accessTokenExpiresUtc: "1717753038" + accessTokenType: "bearer" + types: + - org.camaraproject.sim-swap-subscriptions.v0.swapped + config: + subscriptionDetail: + phoneNumber: "+123456789" + subscriptionExpireTime: '2025-01-17T13:18:23.682Z' + subscriptionMaxEvents: 5 + id: '1119920371' + startsAt: '2024-06-07T16:10:15.302Z' + expiresAt: '2024-06-07T16:10:15.302Z' + status: ACTIVATION_REQUESTED