openapi: 3.0.3
info:
  title: Service Inventory Notification
  description: |
    **This file forms part of Mplify 135.1** 
     

    Supported use cases:
    - Send Notifications

    Copyright 2025 Mplify Alliance and its contributors.

    This file includes content based on the TM Forum Service Inventory Management API (TMF638
    v4.0.1) available at https://github.com/tmforum-apis/TMF638_ServiceInventory,
    which is licensed by the TM Forum under the Apache License version 2.0. Such
    content has been modified by the Mplify Alliance and its contributors.
  version: 2.0.2
servers:
  - url: 'https://{serverBase}/mefApi/allegro/serviceInventoryNotification/v2/'
    variables:
      serverBase:
        description: The base of SOF's URL.
        default: mplify.net
tags:
  - name: Event listeners
    description: Mechanism for SOF to publish *Service* notifications to BUS
paths:
  /listener/serviceCreateEvent:
    post:
      tags:
        - Event listeners
      summary: Service Create Event endpoint
      description:
        This endpoint is used to receive notifications on Service Create Events
      operationId: ServiceCreateEvent
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ServiceCreateEvent'
        required: true
      responses:
        '204':
          description:
            'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
  /listener/serviceDeleteEvent:
    post:
      tags:
        - Event listeners
      summary: Service Delete Event endpoint
      description:
        This endpoint is used to receive notifications on Service Delete Events
      operationId: serviceDeleteEvent
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ServiceDeleteEvent'
        required: true
      responses:
        '204':
          description:
            'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
  /listener/serviceStateChangeEvent:
    post:
      tags:
        - Event listeners
      summary: Service State Change Event endpoint
      description: >-
        This endpoint is used to receive notifications on Service State Change
        Events
      operationId: serviceStateChangeEvent
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ServiceStateChangeEvent'
        required: true
      responses:
        '204':
          description:
            'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
  /listener/serviceAttributeValueChangeEvent:
    post:
      tags:
        - Event listeners
      summary: Service Attribute Value Change Event endpoint
      description: >-
        This endpoint is used to receive notifications on Service Attribute
        Value Change Events
      operationId: serviceAttributeValueChangeEvent
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/ServiceAttributeValueChangeEvent'
        required: true
      responses:
        '204':
          description:
            'No Content (https://tools.ietf.org/html/rfc7231#section-6.3.5)'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error403'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error500'
components:
  schemas:
    Error:
      description: >
        Standard Class used to describe API response error

        Not intended to be use directly. The `code` in the HTTP header is used
        as a discriminator for the type of error returned in runtime.
      type: object
      properties:
        reason:
          description: >-
            Text that explains the reason for error. This can be shown to a
            client user.
          type: string
          maxLength: 255
        message:
          description: >-
            Text that provide mode details and corrective actions related to
            the error. This can be shown to a client user.
          type: string
        referenceError:
          description: url pointing to documentation describing the error
          type: string
          format: uri
      required:
        - reason
    Error400:
      description:
        'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)'
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              description: >-
                One of the following error codes:

                - missingQueryParameter: The URI is missing a required
                query-string parameter

                - missingQueryValue: The URI is missing a required query-string
                parameter value

                - invalidQuery: The query section of the URI is invalid.

                - invalidBody: The request has an invalid body
              $ref: '#/components/schemas/Error400Code'
          required:
            - code
    Error400Code:
      description: >-
        One of the following error codes:

        - missingQueryParameter: The URI is missing a required query-string
        parameter

        - missingQueryValue: The URI is missing a required query-string
        parameter value

        - invalidQuery: The query section of the URI is invalid.

        - invalidBody: The request has an invalid body
      type: string
      enum:
        - missingQueryParameter
        - missingQueryValue
        - invalidQuery
        - invalidBody
    Error401:
      description:
        'Unauthorized.  (https://tools.ietf.org/html/rfc7235#section-3.1)'
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              description: >-
                One of the following error codes:

                - missingCredentials: No credentials provided.

                - invalidCredentials: Provided credentials are invalid or
                expired
              $ref: '#/components/schemas/Error401Code'
          required:
            - code
    Error401Code:
      description: |-
        One of the following error codes:
        - missingCredentials: No credentials provided.
        - invalidCredentials: Provided credentials are invalid or expired
      type: string
      enum:
        - missingCredentials
        - invalidCredentials
    Error403:
      description:
        'Forbidden. (https://tools.ietf.org/html/rfc7231#section-6.5.3)'
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              description: |-
                This code indicates that the server understood
                the request but refuses to authorize it because
                of one of the following error codes:
                - accessDenied: Access denied
                - forbiddenRequester: Forbidden requester
                - tooManyUsers: Too many users
              $ref: '#/components/schemas/Error403Code'
          required:
            - code
    Error403Code:
      description: |-
        This code indicates that the server understood
        the request but refuses to authorize it because
        of one of the following error codes:
        - accessDenied: Access denied
        - forbiddenRequester: Forbidden requester
        - tooManyUsers: Too many users
      type: string
      enum:
        - accessDenied
        - forbiddenRequester
        - tooManyUsers
    Error500:
      description: >-
        Internal Server Error.
        (https://tools.ietf.org/html/rfc7231#section-6.6.1)
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              description: >-
                One of the following error codes:

                - internalError: Internal server error - the server encountered
                an unexpected condition that prevented it from fulfilling the
                request.
              type: string
              enum:
                - internalError
          required:
            - code
    Event:
      description: >-
        Event class is used to describe information structure used for
        notification.
      type: object
      properties:
        eventId:
          description: Id of the event
          type: string
        eventTime:
          description: Date-time when the event occurred
          type: string
          format: date-time
        eventType:
          description: The type of the notification.
          type: string
        event:
          description: The event linked to the involved resource object
          type: object
      required:
        - event
        - eventId
        - eventTime
        - eventType
    ServiceAttributeValueChangeEvent:
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          properties:
            eventType:
              description: |
                Indicates the type of the event.
              type: string
              enum:
                - serviceAttributeValueChangeEvent
            event:
              description: |
                A reference to the object that is source of the notification.
              $ref: '#/components/schemas/ServiceEventPayload'
          required:
            - event
            - eventType
    ServiceCreateEvent:
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          properties:
            eventType:
              description: |
                Indicates the type of the event.
              type: string
              enum:
                - serviceCreateEvent
            event:
              description: |
                A reference to the object that is source of the notification.
              $ref: '#/components/schemas/ServiceEventPayload'
          required:
            - event
            - eventType
    ServiceDeleteEvent:
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          properties:
            eventType:
              description: |
                Indicates the type of the event.
              type: string
              enum:
                - serviceDeleteEvent
            event:
              description: |
                A reference to the object that is source of the notification.
              $ref: '#/components/schemas/ServiceEventPayload'
          required:
            - event
            - eventType
    ServiceEventPayload:
      description: The identifier of the Service being subject of this event.
      type: object
      properties:
        id:
          description: ID of the Service
          type: string
        href:
          description: Hyperlink to access the Service
          type: string
      required:
        - id
    ServiceStateChangeEvent:
      allOf:
        - $ref: '#/components/schemas/Event'
        - type: object
          properties:
            eventType:
              description: |
                Indicates the type of the event.
              type: string
              enum:
                - serviceStateChangeEvent
            event:
              description: |
                A reference to the object that is source of the notification.
              $ref: '#/components/schemas/ServiceStateChangeEventPayload'
          required:
            - event
            - eventType
    ServiceStateChangeEventPayload:
      description: The identifier of the Service being subject of this event.
      type: object
      properties:
        id:
          description: ID of the Service
          type: string
        href:
          description: Hyperlink to access the Service
          type: string
        state:
          description: The life cycle state of the service.
          $ref: '#/components/schemas/ServiceStateType'
      required:
        - id
        - state
    ServiceStateType:
      description: |
        Valid values for the lifecycle state of the Service.

        | State              | Description                                                                                                           |
        | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
        | feasibilityChecked | Initial check whether the necessary resources are available and sufficient for the installation of a given service.   |
        | designed           | The Service is designed. The resources are identified and/or allocated, but not reserved.                             |
        | reserved           | All required resources for given service are reserved and ready.                                                      |
        | inactive           | The service is deactivated and is no longer available.                                                                |
        | active             | The service is fully available and active                                                                             |
        | terminated         | The service is 'logically deleted'. All associated resources are freed and made available for service to other users. |
      type: string
      enum:
        - feasibilityChecked
        - designed
        - reserved
        - inactive
        - active
        - terminated