MTN Group Service API

openapi: 3.2.0
info:
  title: Activation and Configuration Service API
  description: "## TMF API Reference: TMF640 - Service Activation and Configuration\n\n Version 4.0 \n\nService Activation and Configuration API goal is to provide the ability to activate and configure Service. This API features Monitor pattern allowing to manage service configuration/activation asynchronous request (server side will provide monitor as POST/PATCH response) \n\n### TMF640 performs the following Operations on service resource :\n- Retrieve a service or a collection of services depending on filter criteria\n- Partial update of an service\n- Create a service (including default values and creation rules)\n- Delete a service (for administration purposes)\n- Manage notification of events\n\n### Monitor Resource\n\nMonitor resource is used to track and log activation and/or configuration request\n\n### TMF640 provides following operation on Monitor resource:\n\n- Retrieval of a monitor or a collection of monitor\n\nCopyright © TM Forum 2019; All Rights Reserved"
  version: 4.0.0
servers:
- url: http://api.mtn.com/v1
tags:
- name: service
paths:
  /service:
    get:
      operationId: listService
      summary: List or find Service objects
      description: This operation list or find Service entities
      tags:
      - service
      parameters:
      - name: fields
        description: Comma-separated properties to be provided in response
        required: false
        in: query
        schema:
          type: string
      - name: offset
        description: Requested index for start of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      - name: limit
        description: Requested number of resources to be provided in response
        required: false
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Success
          headers:
            X-Result-Count:
              description: Actual number of items returned in the response body
              schema:
                type: integer
            X-Total-Count:
              description: Total number of items matching criteria
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createService
      summary: Creates a Service
      description: This operation creates a Service entity.
      tags:
      - service
      responses:
        '201':
          description: Created
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Service'
        '202':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/Service_Create'
        description: The Service to be created
        required: true
  /service/{id}:
    get:
      operationId: retrieveService
      summary: Retrieves a Service by ID
      description: This operation retrieves a Service entity. Attribute selection is enabled for all first level attributes.
      tags:
      - service
      parameters:
      - name: id
        description: Identifier of the Service
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Comma-separated properties to provide in response
        required: false
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchService
      summary: Updates partially a Service
      description: This operation updates partially a Service entity.
      tags:
      - service
      parameters:
      - name: id
        description: Identifier of the Service
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Updated
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/Service_Update'
        description: The Service to be updated
        required: true
    delete:
      operationId: deleteService
      summary: Deletes a Service
      description: This operation deletes a Service entity.
      tags:
      - service
      parameters:
      - name: id
        description: Identifier of the Service
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: Deleted
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OrderItemActionType:
      type: string
      description: action to be performed on the product
      enum:
      - add
      - modify
      - delete
      - noChange
    RelatedParty:
      type: object
      description: Related Entity reference. A related party defines party or party role linked to a specific entity.
      required:
      - '@referredType'
      - id
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        name:
          type: string
          description: Name of the related entity.
        role:
          type: string
          description: Role played by the related party
        '@baseType':
          example: ResourceSpecification
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          example: LogicalResourceSpecification
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    ServiceSpecificationRef:
      type: object
      description: 'Service specification reference: ServiceSpecification(s) required to realize a ProductSpecification.'
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        name:
          type: string
          description: Name of the related entity.
        version:
          type: string
          description: Service specification version
        '@baseType':
          example: ResourceSpecification
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          example: LogicalResourceSpecification
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
    Service_Update:
      type: object
      description: 'Service is a base class for defining the Service hierarchy. All Services are characterized as either being possibly visible and usable by a Customer or not. This gives rise to the two subclasses of Service: CustomerFacingService and ResourceFacingService.

        Skipped properties: id,href'
      properties:
        category:
          type: string
          description: Is it a customer facing or resource facing service
        description:
          type: string
          description: Free-text description of the service
        endDate:
          type: string
          format: date-time
          description: Date when the service ends
        hasStarted:
          type: boolean
          description: If TRUE, this Service has already been started
        isBundle:
          type: boolean
          description: If true, the service is a ServiceBundle which regroup a service hierachy. If false, the service is a 'atomic' service (hierachy leaf).
        isServiceEnabled:
          type: boolean
          description: 'If FALSE and hasStarted is FALSE, this particular Service has NOT been enabled for use - if FALSE and hasStarted is TRUE then the service has failed '
        isStateful:
          type: boolean
          description: If TRUE, this Service can be changed without affecting any other services
        name:
          type: string
          description: Name of the service
        serviceType:
          type: string
          description: Business type of the service
        startDate:
          type: string
          format: date-time
          description: Date when the service starts
        startMode:
          type: string
          description: 'This attribute is an enumerated integer that indicates how the Service is started, such as: 0: Unknown; 1: Automatically by the managed environment; 2: Automatically by the owning device; 3: Manually by the Provider of the Service; 4: Manually by a Customer of the Provider; 5: Any of the above'
        feature:
          type: array
          items:
            $ref: '#/components/schemas/Feature'
          description: 'A list of feature associated with this service '
        note:
          type: array
          items:
            $ref: '#/components/schemas/Note'
          description: A list of notes made on this service
        place:
          type: array
          items:
            $ref: '#/components/schemas/RelatedPlaceRefOrValue'
          description: A list of places (Place [*]). Used to define a place useful for the service (for example a geographical place whre the service is installed)
        relatedEntity:
          type: array
          items:
            $ref: '#/components/schemas/RelatedEntityRefOrValue'
          description: 'A list of related  entity in relationship with this service '
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          description: A list of related party references (RelatedParty [*]). A related party defines party or party role linked to a specific entity
        serviceCharacteristic:
          type: array
          items:
            $ref: '#/components/schemas/Characteristic'
          description: 'A list of characteristics that characterize this service (ServiceCharacteristic [*]) '
        serviceOrderItem:
          type: array
          items:
            $ref: '#/components/schemas/RelatedServiceOrderItem'
          description: A list of service order items related to this service
        serviceRelationship:
          type: array
          items:
            $ref: '#/components/schemas/ServiceRelationship'
          description: A list of service relationships (ServiceRelationship [*]). Describes links with other service(s) in the inventory (useful for describing relies-on, relies-from between CFS for example).
        serviceSpecification:
          $ref: '#/components/schemas/ServiceSpecificationRef'
          description: The specification from which this service was instantiated
        state:
          $ref: '#/components/schemas/ServiceStateType'
          description: The life cycle state of the service, such as designed, reserved, active, etc...
        supportingResource:
          type: array
          items:
            $ref: '#/components/schemas/ResourceRef'
          description: 'A list of supporting resources (SupportingResource [*]).Note: only Service of type RFS can be associated with Resources'
        supportingService:
          type: array
          items:
            $ref: '#/components/schemas/ServiceRefOrValue'
          description: A list of supporting services (SupportingService [*]). A collection of services that support this service (bundling, link CFS to RFS)
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    ConstraintRef:
      type: object
      description: Constraint reference. The Constraint resource represents a policy/rule applied to an entity or entity spec.
      properties:
        id:
          type: string
          description: reference id to the target constraint
        href:
          type: string
          description: Hyperlink reference to the target constraint
        name:
          type: string
          description: Name given to the constraint
        version:
          type: string
          description: constraint version
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
        '@referredType':
          type: string
          description: The (class) type of the referred constraint
      required:
      - id
    ResourceRef:
      type: object
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        name:
          type: string
          description: Name of the related entity.
        '@baseType':
          example: ResourceSpecification
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          example: LogicalResourceSpecification
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
    FeatureRelationship:
      type: object
      description: Configuration feature
      required:
      - name
      - relationshipType
      properties:
        id:
          type: string
          description: Unique identifier of the target feature.
        name:
          type: string
          description: This is the name of the target feature.
        relationshipType:
          type: string
          description: This is the type of the feature relationship.
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which this feature relationship is valid.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    Any: {}
    ServiceStateType:
      type: string
      description: Valid values for the lifecycle state of the service
      enum:
      - feasibilityChecked
      - designed
      - reserved
      - inactive
      - active
      - terminated
    Service:
      type: object
      description: 'Service is a base class for defining the Service hierarchy. All Services are characterized as either being possibly visible and usable by a Customer or not. This gives rise to the two subclasses of Service: CustomerFacingService and ResourceFacingService.'
      properties:
        id:
          type: string
          description: Unique identifier of the service
        href:
          type: string
          description: Reference of the service
        category:
          type: string
          description: Is it a customer facing or resource facing service
        description:
          type: string
          description: Free-text description of the service
        endDate:
          type: string
          format: date-time
          description: Date when the service ends
        hasStarted:
          type: boolean
          description: If TRUE, this Service has already been started
        isBundle:
          type: boolean
          description: If true, the service is a ServiceBundle which regroup a service hierachy. If false, the service is a 'atomic' service (hierachy leaf).
        isServiceEnabled:
          type: boolean
          description: 'If FALSE and hasStarted is FALSE, this particular Service has NOT been enabled for use - if FALSE and hasStarted is TRUE then the service has failed '
        isStateful:
          type: boolean
          description: If TRUE, this Service can be changed without affecting any other services
        name:
          type: string
          description: Name of the service
        serviceDate:
          type: string
          description: Date when the service was created (whatever its status).
        serviceType:
          type: string
          description: Business type of the service
        startDate:
          type: string
          format: date-time
          description: Date when the service starts
        startMode:
          type: string
          description: 'This attribute is an enumerated integer that indicates how the Service is started, such as: 0: Unknown; 1: Automatically by the managed environment; 2: Automatically by the owning device; 3: Manually by the Provider of the Service; 4: Manually by a Customer of the Provider; 5: Any of the above'
        feature:
          type: array
          items:
            $ref: '#/components/schemas/Feature'
          description: 'A list of feature associated with this service '
        note:
          type: array
          items:
            $ref: '#/components/schemas/Note'
          description: A list of notes made on this service
        place:
          type: array
          items:
            $ref: '#/components/schemas/RelatedPlaceRefOrValue'
          description: A list of places (Place [*]). Used to define a place useful for the service (for example a geographical place whre the service is installed)
        relatedEntity:
          type: array
          items:
            $ref: '#/components/schemas/RelatedEntityRefOrValue'
          description: 'A list of related  entity in relationship with this service '
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          description: A list of related party references (RelatedParty [*]). A related party defines party or party role linked to a specific entity
        serviceCharacteristic:
          type: array
          items:
            $ref: '#/components/schemas/Characteristic'
          description: 'A list of characteristics that characterize this service (ServiceCharacteristic [*]) '
        serviceOrderItem:
          type: array
          items:
            $ref: '#/components/schemas/RelatedServiceOrderItem'
          description: A list of service order items related to this service
        serviceRelationship:
          type: array
          items:
            $ref: '#/components/schemas/ServiceRelationship'
          description: A list of service relationships (ServiceRelationship [*]). Describes links with other service(s) in the inventory (useful for describing relies-on, relies-from between CFS for example).
        serviceSpecification:
          $ref: '#/components/schemas/ServiceSpecificationRef'
          description: The specification from which this service was instantiated
        state:
          $ref: '#/components/schemas/ServiceStateType'
          description: The life cycle state of the service, such as designed, reserved, active, etc...
        supportingResource:
          type: array
          items:
            $ref: '#/components/schemas/ResourceRef'
          description: 'A list of supporting resources (SupportingResource [*]).Note: only Service of type RFS can be associated with Resources'
        supportingService:
          type: array
          items:
            $ref: '#/components/schemas/ServiceRefOrValue'
          description: A list of supporting services (SupportingService [*]). A collection of services that support this service (bundling, link CFS to RFS)
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    Error:
      description: Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)
      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
          format: uri
          description: URI of documentation describing the error.
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class.
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name.
    TimePeriod:
      type: object
      description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
      properties:
        endDateTime:
          example: '1985-04-12T23:20:50.52Z'
          type: string
          format: date-time
          description: End of the time period, using IETC-RFC-3339 format
        startDateTime:
          example: '1985-04-12T23:20:50.52Z'
          type: string
          format: date-time
          description: Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          type: string
          description: When sub-classing, this defines the sub-class entity name
    RelatedPlaceRefOrValue:
      type: object
      description: Related Entity reference. A related place defines a place described by reference or by value linked to a specific entity. The polymorphic attributes @type, @schemaLocation & @referredType are related to the place entity and not the RelatedPlaceRefOrValue class itself
      required:
      - role
      properties:
        id:
          type: string
          description: Unique identifier of the place
        href:
          type: string
          description: Unique reference of the place
        name:
          type: string
          description: A user-friendly name for the place, such as [Paris Store], [London Store], [Main Home]
        role:
          type: string
        '@baseType':
          example: ResourceSpecification
          type: string
          description: When sub-classing, this defines the super-class
        '@schemaLocation':
          example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
          type: string
          format: uri
          description: A URI to a JSON-Schema file that defines additional attributes and relationships
        '@type':
          example: LogicalResourceSpecification
          type: string
          description: When sub-classing, this defines the sub-class Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
    ServiceRelationship:
      type: object
      required:
      - relationshipType
      properties:
        relationshipType:
          type: string
        ServiceRelationshipCharacteristic:
          type: array
          items:
            $ref: '#/components/schemas/Characteristic'
        service:
          $ref: '#/components/schemas/ServiceRefOrValue'
        '@baseType':
          type: string
          description: When sub-classing, this defines the super-cl

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-service-api-openapi.yml