swagger: '2.0'
info:
  description: >-
    Notification API can be used to notify customers applications when a certain event happens in the system. In order for a customer to get notifications,
    certain actions should be performed, such as creating a subscription for a required set of events and an application, and then periodically send requests
    to see if there are any new notifications for a specific subscription.

    This API also contains an API for deleting a subscription (unsubscribe) as well as getting statical information about a specific subscription.
    It supports the v2 events that are configured in events list.

    **API-security**

    All endpoints of this API are protected endpoints; they can only be used if
    a valid OAuth 'access token' is provided. The access token need to be
    associated with the valid authorisation 'scope'. Scopes that are relevant
    for this API are:
        - notification:consent:administrator: Allows to create and delete subscription
        - notification:consent:consumer: Allows to retrieve subscriptions and notifications

    **Typical flow**

    The typical flow for using this API is:
      * iWelcome customer contacts iWelcome to register a client application for using the notification API. iWelcome provides customer with client id and client secret and configures the scope 'notification:consent:consumer' for this app, identified by client id
      * For the notification administrator to manage the subscriptions, a new client with scope 'notification:consent:administrator' is configured
      * The notification administrator creates a subscription for the client id (application), using the notification subscription endpoint. Creating a new subscription requires the 'notification:consent:administrator' scope which can be obtained by any Oauth2/OIDC flow
      * The notification consumer (customer application) uses Oauth2/OIDC endpoints to obtain an access token that can be used for the notification API. In order to be able to get notifications the access token has to contain the 'notification:consent:consumer' scope
      * The notification consumer (customer application) repeatedly invokes the 'notifications' endpoint to obtain notifications
      * The notification administrator can unsubscribe the client when notifications are no longer needed by that client
  version: '0.1'
  title: Notification API
host: www.iwelcome.com
basePath: /
tags:
  - name: Notification subscription V1
  - name: Notification retrieval V1
schemes:
  - https
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://example-domain-uri.com/auth/oauth2.0/v1/authorize'
    tokenUrl: 'https://example-domain-uri.com/auth/oauth2.0/v1/token'
    scopes:
      notification:consent:administrator: Allows to create and delete subscription
      notification:consent:consumer: Allows to get subscriptions
consumes:
  - application/vnd.iwelcome.v1+json
produces:
  - application/vnd.iwelcome.v1+json
paths:
  /notification/v1/subscriptions:
    post:
      security:
        - OAuth2: [ 'notification:consent:administrator']
      tags:
        - Notification subscription V1
      summary: Subscribe to notifications for any events
      description: >-
        This API can be used to create a new subscription.
        While creating a new subscription, a list of event ids and a client id should be provided. Whenever there will
        be a new event generated in the system with an id which is in the list sent on the request, the event will be also available when calling the 'notifications' endpoint.
        The response of this API  contains some information about the newly created subscription along with the subscription id which can be later on used to get the notifications.
        In order to be able to access this API, 'notification:consent:administrator' scope is required.
      operationId: createSubscription
      parameters:
        - in: body
          name: body
          description: Create new subscription request
          required: false
          schema:
            $ref: '#/definitions/NewSubscription'
      consumes:
        - application/vnd.iwelcome.v1+json
      produces:
        - application/vnd.iwelcome.v1+json
      responses:
        201:
          description: 'Successfully subscribed to resources'
          schema:
            $ref: '#/definitions/SubscriptionResponse'
        400:
          description: 'Bad request, error codes: NOT000001, NOT000009'
          schema:
            $ref: '#/definitions/SubscriptionResponse'
        401:
          description: 'Authorization failure, error code: NOT000008'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: NOT000007'
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: 'client_id not found, error code: NOT000002'
          schema:
            $ref: '#/definitions/ErrorResponse'
        409:
          description: 'Duplicate Registration, error code: NOT000003'
          schema:
            $ref: '#/definitions/ErrorResponse'
        429:
          description: 'Too many requests, error code: NOT000004'
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: 'Internal server error, error code: NOT000005'
          schema:
            $ref: '#/definitions/ErrorResponse'
  /notification/v1/subscriptions/{id}:
    get:
      security:
        - OAuth2: [ 'notification:consent:consumer' ]
      tags:
        - Notification subscription V1
      summary: Get the details of a subscription
      description: >-
        This endpoint can be used to get the 'static' details of a subscription.
        Also the last time notifications were retrieved from the subscription is
        returned as well as the number of remaining notifications. The number of
        remaining notifications is a dynamic number since new
        notifications may be added constantly. Two consecutive calls to this
        endpoint may return a different value this number.
        In order to be able to access this API, 'notification:consent:consumer' scope is required. The endpoint will only return the subscription if the
        access token sent on the request has, apart from the required scope mentioned above, the same client_id that was used to create the subscription identified with the id sent in the url.
      operationId: getSubscription
      parameters:
        - name: id
          in: path
          description: Subscription id
          required: true
          type: string
          pattern: ^[\p{L}0-9\._\-]+$
      responses:
        200:
          description: The subscribed resources
          schema:
            $ref: '#/definitions/SubscriptionResponse'
        400:
          description: 'Invalid input, error code: NOT000001'
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Authorization failure, error code: NOT000008'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: NOT000007'
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: 'subscription_id not found, error code: NOT000006'
          schema:
            $ref: '#/definitions/ErrorResponse'
        429:
          description: 'Too many requests, error code: NOT000004'
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: 'Internal server error, error code: NOT000005'
          schema:
            $ref: '#/definitions/ErrorResponse'
    delete:
      security:
        - OAuth2: [ 'notification:consent:administrator' ]
      tags:
        - Notification subscription V1
      summary: Unsubscribe notifications
      operationId: deleteSubscription
      description: >-
        Clients can use this endpoint to unsubscribe from notifications for a set of events.
        In order to be able to access this API, 'notification:consent:administrator' scope is required.
      parameters:
        - name: id
          in: path
          description: Subscription id
          required: true
          type: string
          pattern: ^[\p{L}0-9\._\-]+$
      responses:
        204:
          description: Successfully delete subscription to the resource
        400:
          description: 'Invalid input, error code: NOT000001'
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Authorization failure, error code: NOT000008'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: NOT000007'
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: 'subscription_id not found, error code: NOT000006'
          schema:
            $ref: '#/definitions/ErrorResponse'
        429:
          description: 'Too many requests, error code: NOT000004'
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: 'Internal server error, error code: NOT000005'
          schema:
            $ref: '#/definitions/ErrorResponse'
  /notification/v1/subscriptions/{id}/notifications:
    get:
      security:
        - OAuth2: [ 'notification:consent:consumer' ]
      tags:
        - Notification retrieval V1
      summary: >-
        Retrieves notifications for the events that the client subscribed to
      description: >-
        'Retrieve a set of notifications of a subscription identified by a unique id.
        In order to be able to access this API, 'notification:consent:consumer' scope is required.
        The endpoint will only return the subscription if the access token sent on the request has, apart from the required scope mentioned above,
        the same client_id that was used to create the subscription identified with the id sent in the url.

        Once a notification is retrieved, the same notification cannot be
        retrieved again for the same subscription. This means that this endpoint
        is NOT idempotent according to REST-definitions.

        Clients need to retrieve the notifications on a regular (e.g. daily) basis.
        Notifications will not be kept indefinitely, but it will be kept for a configurable amount of time which is set by default to 6 hours.
        The schema for these resources depend on the eventIds to which the client has subscribed to.
      operationId: getNotifications
      parameters:
        - name: id
          in: path
          description: subscription id
          required: true
          type: string
          pattern: ^[\p{L}0-9\._\-]+$
      responses:
        200:
          description: Successfully created a list of resources
          schema:
            $ref: '#/definitions/NotificationsResponse'
        400:
          description: 'Invalid input, error code: NOT000001'
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: 'Authorization failure, error code: NOT000008'
          schema:
            $ref: '#/definitions/ErrorResponse'
        403:
          description: 'Permissions denied, error code: NOT000007'
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: 'subscription_id not found, error code: NOT000006'
          schema:
            $ref: '#/definitions/ErrorResponse'
        429:
          description: 'Too many requests, error code: NOT000004'
          schema:
            $ref: '#/definitions/ErrorResponse'
        500:
          description: 'Internal server error, error code: NOT000005'
          schema:
            $ref: '#/definitions/ErrorResponse'
definitions:
  NewSubscription:
    type: object
    required:
      - event_type_ids
      - client_id
    properties:
      event_type_ids:
        description: >-
          The list of events to subscribe for notifications
        type: array
        minLength: 1
        minItems: 1
        uniqueItems: true
        items:
          type: string
          pattern: ^[0-9]+$
      client_id:
        type: string
        pattern: ^[\p{L}0-9\._\-]+$
        description: >-
          The oauth2 client identifier issued to the client during the registration
          process, as indicated by OAuth RFC 6749.
  SubscriptionResponse:
    type: object
    required:
      - id
    properties:
      id:
        type: string
        description: >-
          Unique identifier of the subscription
      subscription:
        $ref: '#/definitions/SubscriptionResourceResponse'
      subscription_status:
        $ref: '#/definitions/SubscriptionStatusResponse'
  SubscriptionResourceResponse:
    type: object
    required:
      - event_type_ids
    properties:
      client_id:
        type: string
        description: The client_id for the subscribed application.
      event_type_ids:
        description: >-
          The list of event id for which the notifications are made available
          for the client.
        type: array
        uniqueItems: true
        items:
          type: string
      subscribed_by:
        description: The user id of the authenticated user or tha application that created the subscription.
        type: string
        example: ed7afb3e75e8482db1cab4e2950ae50c  or notificationAdminApp.
      subscription_date:
        description: >-
          The date on which the client application subscribed. Same format as other APIs...
        type: string
        format: date-time
        example: '2018-01-23T04:56:22Z'
      notification_url:
        description: >-
          The url to use by the client application to retrieve the
          notifications.
        type: string
      notification_page_size:
        description: The amount of objects in the notification responses.
        type: integer
  SubscriptionStatusResponse:
    properties:
      last_request_date:
        type: string
        format: date-time
        example: '2018-01-23T04:56:22Z'
      number_of_remaining_notifications:
        type: integer
  NotificationsResponse:
    type: object
    properties:
      page:
        type: integer
        description: the sequence number of the page
      size:
        type: integer
        description: >-
          the number or results returned in the current response. This number
          cannot exceed the notification_page_size.
      results:
        type: array
        items:
          type: object
          description: >-
            Represent the events that the customer subscribed for.
            The schema for these results is not standard due to the type of events for which there is a subscription for.
  ErrorResponse:
    type: object
    properties:
      code:
        type: string
        enum:
          - NOT000001
          - NOT000002
          - NOT000003
          - NOT000004
          - NOT000005
          - NOT000006
          - NOT000007
          - NOT000008
          - NOT000009
        description: |
          Error code:
            * NOT000001: Bad request.
            * NOT000002: client_id not found.
            * NOT000003: Duplicate Registration.
            * NOT000004: Too many requests.
            * NOT000005: Internal server error.
            * NOT000006: subscription_id not found.
            * NOT000007: Access token is valid but doesn't have the right scope.
            * NOT000008: No valid access token.
            * NOT000009: Failed to create subscription.
      description:
        type: string
        description: detail error message

