GSMA Open Gateway events subscription API

openapi: 3.2.0
info:
  title: Open Gateway Operate API Onboarding and Ordering events subscription API
  description: "**TMF931 - API Ordering, Developer & Application Onboarding and Management**   \n\nThis Operate API specification covers the onboarding operations between Channel Partners and Operators as described by GSMA. It offers a consolidation of multiple TM Forum based APIs into a single specification (a component suite). This API specification proposes : \n- Application Owner (Developer) Management (acceptance, onboarding, lifecycle management)  \n- Application Management (acceptance, onboarding, lifecycle management)  \n- Service API Management (ordering, retrieving)\n\nThis API is a composite DCS (Domain Context Specialization) of the following TMF Open APIs for Open Gateway context\n- TMF622 Product Ordering Management v5.0\n- TMF637 Product Inventory Management v5.0\n- TMF669 Party Role Management v5.0\n- TMF639 Resource Inventory v5.0\n\nCopyright © TM Forum 2025. All Rights Reserved\n"
  version: 5.2.1
  x-generation-tooling-version: v8.5.15
  x-generation-data-model-version: unknown
  x-generation-date: '2025-12-11T09:49:01.463Z'
  x-api-id: TMF931
  license:
    name: Apache License 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: '{apiRoot}/openGatewayOperateAPIOnboardingAndOrdering/v5/'
  variables:
    apiRoot:
      default: https://serverRoot/tmf-api/openGatewayOperateAPIOnboardingAndOrdering/v5
      enum:
      - https://serverRoot/tmf-api/openGatewayOperateAPIOnboardingAndOrdering/v5
tags:
- name: events subscription
  description: Endpoints to register and terminate an Event Listener
paths:
  /hub:
    post:
      operationId: createHub
      summary: Create a subscription (hub) to receive Events
      description: Sets the communication endpoint to receive Events.
      tags:
      - events subscription
      requestBody:
        $ref: '#/components/requestBodies/Hub_FVO'
      responses:
        '201':
          $ref: '#/components/responses/Hub'
        default:
          $ref: '#/components/responses/Error'
  /hub/{id}:
    get:
      operationId: hubGet
      summary: Retrieve a subscription (hub)
      description: This operation retrieves the subscription to receive Events.
      tags:
      - events subscription
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          $ref: '#/components/responses/Hub'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: hubDelete
      summary: Remove a subscription (hub) to receive Events
      description: This operation removes the subscription to receive Events.
      tags:
      - events subscription
      parameters:
      - $ref: '#/components/parameters/Id'
      responses:
        '204':
          description: Deleted
        default:
          $ref: '#/components/responses/Error'
components:
  responses:
    Hub:
      description: Notified
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Hub'
          examples:
            basic:
              summary: Hub example
              value:
                '@type': Hub
                callback: https://host/tmf-api/specificAPIName/v5/listener/specificEventListener
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            basic:
              summary: Error example
              value:
                '@type': Error
                code: ERR001
                reason: Missing information
                message: Please provide the additional example information
                referenceError: https://host/errors
  schemas:
    Error:
      discriminator:
        propertyName: '@type'
        mapping:
          Error: '#/components/schemas/Error'
      allOf:
      - $ref: '#/components/schemas/Extensible'
      - type: object
        required:
        - code
        - reason
        properties:
          code:
            type: string
            description: Application relevant detail, defined in the API or a common list.
          reason:
            type: string
            description: Explanation of the reason for the error which can be shown to a client user.
          message:
            type: string
            description: More details and corrective actions related to the error which can be shown to a client user.
          status:
            type: string
            description: HTTP Error code extension
          referenceError:
            type: string
            description: URI of documentation describing the error.
      description: Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)
    Extensible:
      type: object
      description: Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema  MUST be extended with the @type
      properties:
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
      required:
      - '@type'
    Addressable:
      type: object
      description: Base schema for addressable entities
      properties:
        href:
          type: string
          description: Hyperlink reference
        id:
          type: string
          description: unique identifier
    Hub_FVO:
      type: object
      description: Sets the communication endpoint address the service instance must use to deliver notification information
      required:
      - callback
      allOf:
      - $ref: '#/components/schemas/Extensible'
      - properties:
          callback:
            type: string
            description: The callback being registered.
          query:
            type: string
            description: additional data to be passed
    Hub:
      type: object
      description: Sets the communication endpoint address the service instance must use to deliver notification information
      allOf:
      - $ref: '#/components/schemas/Entity'
      - properties:
          id:
            type: string
            description: Id of the listener
          callback:
            type: string
            description: The callback being registered.
          query:
            type: string
            description: additional data to be passed
        required:
        - callback
    Entity:
      type: object
      description: Base entity schema for use in TMForum Open-APIs. Property.
      allOf:
      - $ref: '#/components/schemas/Extensible'
      - $ref: '#/components/schemas/Addressable'
  requestBodies:
    Hub_FVO:
      description: Data containing the callback endpoint to deliver the information
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Hub_FVO'
          examples:
            Basic Hub Example Request:
              value:
                '@type': Hub
                callback: https://host/tmf-api/specificAPIName/v5/listener/specificEventListener
                query: data
      required: true
  parameters:
    Id:
      name: id
      required: true
      schema:
        type: string
      in: path
      description: Identifier of the Resource