openapi: 3.0.0
info:
  version: 0.0.5
  title: Notification Subscription API
  description: To receive notifications, an event notification subscriptions must be completed by providing the details of the events a subscriber want to be notified about. This API allows institutions subscribe to events they would like to receive for the BIC8s participating in the notification service. 
    ** You must proceed with Domain Registration first before subscribing to the event notification. 
  contact:
    name: Developer Hub
    url: https://developer.swift.com
    email: developer-support@swift.com
  license:
    name: API Restricted License
    url: https://developer.swift.com/api-license
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/SWIFT-API/Notification-Subscription/0.0.5
  - description: URL for Pilot.
    url: https://api-test.swiftnet.sipn.swift.com/notification-service/v1
  - description: URL for Live.
    url: https://api.swiftnet.sipn.swift.com/notification-service/v1
  - description: URL for Sandbox Environment.
    url: https://sandbox.swift.com/notification-service/v1

security:
  - oauthBearerToken: []
    
tags:
  - name: Subscriptions
    
paths:
  /subscriptions:
    post:
      tags:
        - Subscriptions
      summary: Create Subscription.
      description: Register or subscribe to specific event of interest in the context of an API Service.
      operationId: createSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
            examples:
              POSTSubscriptionRequest:
                $ref: '#/components/examples/SubscriptionRequest'
      responses:
        '201':
          description: Created.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                GetSubscriptionResponse:
                  $ref: '#/components/examples/GetSubscriptionResponse'
        '400':
          $ref: '#/components/responses/400-BadRequest'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '406':
          $ref: '#/components/responses/406-NotAcceptable'
        '413':
          $ref: '#/components/responses/413-PayloadTooLarge'
        '415':
          $ref: '#/components/responses/415-UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/429-TooManyRequests'
        '503':
          $ref: '#/components/responses/503-ServiceUnavailable'
        '504':
          $ref: '#/components/responses/504-GatewayTimeout'
        default:
          $ref: '#/components/responses/503-ServiceUnavailable'
    get:
      tags:
        - Subscriptions
      summary: Retrieve Subscriptions.
      description: Retrieve the event subscriptions created on the API service for the calling institution.
      operationId: getSubscriptions
        
      responses:
        '200':
          description: OK
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                  $ref: '#/components/schemas/Subscriptions'
              
        '400':
          $ref: '#/components/responses/400-BadRequest'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '406':
          $ref: '#/components/responses/406-NotAcceptable'
        '429':
          $ref: '#/components/responses/429-TooManyRequests'
        '503':
          $ref: '#/components/responses/503-ServiceUnavailable'
        '504':
          $ref: '#/components/responses/504-GatewayTimeout'
        default:
          $ref: '#/components/responses/503-ServiceUnavailable'
  /subscriptions/{subscription-id}:
    get:
      tags:
        - Subscriptions
      summary: Retrieve a Subscription.
      description: Retrieve a notification subscription identified by subscription-id.
      operationId: getSubscriptionById
      parameters:
        # path
        - $ref: '#/components/parameters/subscription-id'
        
      responses:
        '200':
          description: OK
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                GetSubscriptionResponse:
                  $ref: '#/components/examples/GetSubscriptionResponse'
        '400':
          $ref: '#/components/responses/400-BadRequest'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-NotFound'
        '406':
          $ref: '#/components/responses/406-NotAcceptable'
        '429':
          $ref: '#/components/responses/429-TooManyRequests'
        '503':
          $ref: '#/components/responses/503-ServiceUnavailable'
        '504':
          $ref: '#/components/responses/504-GatewayTimeout'
        default:
          $ref: '#/components/responses/503-ServiceUnavailable'
    put:
      tags:
        - Subscriptions
      summary: Modify a Subscription.
      description: Modify an existing notification subscription  identified by subscription-id.
      operationId: modifySubscriptionById
      parameters:
        # path
        - $ref: '#/components/parameters/subscription-id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '400':
          $ref: '#/components/responses/400-BadRequest'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-NotFound'
        '413':
          $ref: '#/components/responses/413-PayloadTooLarge'
        '415':
          $ref: '#/components/responses/415-UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/429-TooManyRequests'
        '503':
          $ref: '#/components/responses/503-ServiceUnavailable'
        '504':
          $ref: '#/components/responses/504-GatewayTimeout'
        default:
          $ref: '#/components/responses/503-ServiceUnavailable'
          
    delete:
      tags:
        - Subscriptions
      summary: Delete a Subscription.
      description: Delete an existing notification subscription  identified by subscription-id.
      operationId: deleteSubscriptionById
      parameters:
        # path
        - $ref: '#/components/parameters/subscription-id'
      responses:
        '204':
          description: No Content
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '400':
          $ref: '#/components/responses/400-BadRequest'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-NotFound'
        '429':
          $ref: '#/components/responses/429-TooManyRequests'
        '503':
          $ref: '#/components/responses/503-ServiceUnavailable'
        '504':
          $ref: '#/components/responses/504-GatewayTimeout'
        default:
          $ref: '#/components/responses/503-ServiceUnavailable'
          
  
components:
  schemas:
    Subscriptions:
      type: array
      description: Subscriptions.
      additionalProperties: false
      items: 
        properties:
          subscription_id:
            type: string
            format: uuid
            description: An unique identifier of the subscription.
            example: 41d69890-54d0-41ef-bcfd-b083ad4c6475
          service_name:
            maxLength: 100
            minLength: 1 
            type: string
            description: Name of the API service.
            example: gss.screening.api
          event_types:
            description: Identifies the event type.
            type: array
            items:
              type: string
              pattern: ^[a-zA-Z0-9._-]*$
            example: 
              - com.gss.screening.result-success
              - com.gss.screening.result-failure
          mechanism:
            description: Event delivery mechanism. Default this value to "webhooks". This field is meant for supporting other delivery channels in the future.
            type: string
            pattern: ^[a-zA-Z0-9._-]*$
            example: webhooks
          subscriber_bics:
            description: Filter events subscription per BIC8.
            type: array
            items:
              type: string
              pattern: ^[a-z]{6,6}[a-z2-9][a-np-z0-9]$
            example: 
              - swhqbebb
              - swhetxxx
          endpoint:
            description: Endpoint for receiving service specific events notifications. The endpoint must be defined with https scheme. The domain name used must be a pre-registered routable domain. Please refer to Domain Registration API for more details.
            type: string
            format: uri
            pattern: ^https:\/\/[^\s\/$.?#].[^\s]*$
            maxLength: 1024
            example : https://51d57890-54d0-41ef-bcfd-b983ad4c6475.hooks.swiftnet.sipn.swift.com/api-tracker-events
        required:
        - subscription_id
        - service_name
        - event_types
        - mechanism
        - subscriber_bics
  
    Subscription:
      type: object
      description: Register / Create an event subscription.
      additionalProperties: false
      required:
        - service_name
        - event_types
        - mechanism
        - subscriber_bics
      properties:
        service_name:
          maxLength: 100
          minLength: 1 
          type: string
          description: Name of the API service.
          example: gss.screening.api
        # category
        event_types:
          description: Identifies the event type.
          type: array
          items:
            type: string
            pattern: ^[a-zA-Z0-9._-]*$
          example: 
            - com.gss.screening.result-success
            - com.gss.screening.result-failure
        mechanism:
          description: Event Delivery mechanism
          type: string
          pattern: ^[a-zA-Z0-9._-]*$
          example: webhooks
        subscriber_bics:
          description: Filter events subscription per BIC8.
          type: array
          items:
            type: string
            pattern: ^[a-z]{6,6}[a-z2-9][a-np-z0-9]$
          example: 
            - swhqbebb
            - swhetxxx
        endpoint:
          description: Endpoint for receiving service specific events notifications. The endpoint must be defined with https scheme. The domain name used must be a pre-registered routable domain. Please refer to Domain Registration API for more details.
          type: string
          format: uri
          pattern: ^https:\/\/[^\s\/$.?#].[^\s]*$
          maxLength: 1024
          example : https://51d57890-54d0-41ef-bcfd-b983ad4c6475.hooks.swiftnet.sipn.swift.com/api-tracker-events
      
    SubscriptionResponse:
      type: object
      description: Retrieve a event subscription identified by subscription-id.
      additionalProperties: false
      properties:
        subscription_id:
          type: string
          format: uuid
        service_name:
          maxLength: 100
          minLength: 1        
          type: string
          description: Name of the API Service.
          example: gss.screening.api
        # category
        event_types:
          description: Identifies the event type.
          type: array
          items:
            type: string
            pattern: ^[a-zA-Z0-9._-]*$
        mechanism:
          description: Event delivery mechanism.
          type: string
          pattern: ^[a-zA-Z0-9._-]*$
          example: webhooks
        subscriber_bics:
          description: The BIC(s) to which the events must be delivered when an event occurs. The BIC must be a subscriber of the service related to the events.
          type: array
          items:
            type: string
            pattern: ^[a-z]{6,6}[a-z2-9][a-np-z0-9]$
        endpoint:
          description: Endpoint for receiving service specific events notifications. The endpoint must be defined with https scheme. The domain name used must be a pre-registered routable domain. Please refer to Domain Registration API for more details.
          type: string
          format: uri
          pattern: ^https:\/\/[^\s\/$.?#].[^\s]*$
          maxLength: 1024
          example : https://51d57890-54d0-41ef-bcfd-b983ad4c6475.test.hooks.swiftnet.sipn.swift.com/api-tracker-events
      required:
        - subscription_id
        - service_name
        - event_types
        - mechanism
        - subscriber_bics
            
    Errors:
      description: "Container to return multiple ErrorMessage object. Collection of error can be useful when API needs to return multiple errors, for example validation errors. When the response code conveys application-specific functional semantics and consumer can parse machine-readable error code, this block can be useful. The error response must contain at least one error object."
      type: object
      additionalProperties: false
      required:
        - code
        - severity
        - text
      properties:
        severity:
          description: "Specifies the severity of the error."
          type: string
          enum:
          - Fatal
          - Transient
          - Logic
        code:
          description: "Specifies the custom error code as defined by the service provider."
          type: string
          minLength: 3
          maxLength: 70
        text:
          description: "Specifies the detail error message identifying the cause of the error."
          type: string
          minLength: 1
          maxLength: 255
        

##############################

  headers:
    X-Request-ID:
      description: "Specify an unique end to end tracking request ID. The element will be populated by the SWIFT API gateway"
      schema:
        type: string
        
  parameters:
    X-Request-ID:
      description: 'Specify an unique end to end tracking request ID. The element will be populated by the SWIFT API gateway.'
      name: X-Request-ID
      in: header
      schema:
        type: string
    subscription-id:
      name: subscription-id
      in: path
      description: Identifier of a specific subscription.
      required: true
      schema:
        type: string
        format: uuid
      example: 41d69890-54d0-41ef-bcfd-b083ad4c6475
  responses:
    400-BadRequest:
      description: 'Bad Request'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    401-Unauthorized:
      description: 'Unauthorized'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    403-Forbidden:
      description: 'Forbidden'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    404-NotFound:
      description: 'Not Found'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    405-MethodNotAllowed:
      description: 'Method Not Allowed'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    406-NotAcceptable:
      description: 'Not Acceptable'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    407-ProxyAuthenticationRequired:
      description: 'Proxy Authentication Required'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    409-Conflict:
      description: 'Conflict'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    410-Gone:
      description: 'Gone'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    412-PreconditionFailed:
      description: 'Precondition Failed'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    413-PayloadTooLarge:
      description: 'Payload Too Large'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    415-UnsupportedMediaType:
      description: 'Unsupported Media Type'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    429-TooManyRequests:
      description: 'Too Many Requests'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    500-InternalServerError:
      description: 'Internal Server Error'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    502-BadGateway:
      description: 'Bad Gateway'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    503-ServiceUnavailable:
      description: 'Service Unavailable'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    504-GatewayTimeout:
      description: 'Gateway Timeout'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'

###########################
#  Security Definition    #
###########################            
  securitySchemes:
    oauthBearerToken:
      type: http
      scheme: bearer
      bearerFormat: opaque OAuth 2.0
      description: |
        The access token obtained as a result of OAuth 2.0 flows. SWIFT supports two OAuth grant types for consumption depending on the environment where the API is exposed. 
        
        * MV-SIPN - jwt-bearer grant type [RFC 7523](https://tools.ietf.org/html/rfc7523) with Signed JWT assertion
        * Internet - Password grant type with license credentials.

        This API uses JWT-Bearer grant type.

        Please visit [SWIFT OAuth Token API](https://developer.swift.com/swift-oauth-token-api) page for more information and examples on how to generate an OAuth token.

        In this declaration only the basic security element to transport the bearer token of an OAuth2 process is declared.
            
###########################
#       Examples          #
###########################
  examples:
    SubscriptionRequest:
      summary: Create a subscription
      value:
        service_name: gss.screening.api
        event_types: 
          - com.gss.screening.result-success
          - com.gss.screening.result-failure
        mechanism: webhooks
        subscriber_bics:
          - swhqbebb
          - swhetxxx
        endpoint: https://51d57890-54d0-41ef-bcfd-b983ad4c6475.hooks.swiftnet.sipn.swift.com/api-tracker-events 

    
    GetSubscriptionResponse:
      summary: Get all subscription response
      value:
        subscription_id: 41d69890-54d0-41ef-bcfd-b083ad4c6475
        service_name: gss.screening.api
        event_types: 
          - com.gss.screening.result-success
          - com.gss.screening.result-failure
        mechanism: webhooks
        subscriber_bics: 
          - swhqbebb
          - swhetxxx
        endpoint: https://51d57890-54d0-41ef-bcfd-b983ad4c6475.hooks.swiftnet.sipn.swift.com/api-tracker-events