TM Forum serviceCatalog API

openapi: 3.2.0
info:
  title: Management Service Catalog API
  description: "## TMF API Reference: TMF633 - Service Catalog Management\n\n Version 4.0 \n\nThe Service Catalog API is one of Catalog Management API Family. Service Catalog API goal is to provide a catalog of services. \nService Catalog API performs the following operations on the resource :\n- Retrieve an entity or a collection of entities depending on filter criteria\n- Partial update of an entity (including updating rules)\n- Create an entity (including default values and creation rules)\n- Delete an entity (for administration purposes)\n- Manage notification of events. .\n\nCopyright © TM Forum 2020. All Rights Reserved. "
  version: 4.0.0
servers:
- url: https://serverRoot/tmf-api/serviceCatalogManagement/v4/
tags:
- name: serviceCatalog
paths:
  /serviceCatalog:
    get:
      operationId: listServiceCatalog
      summary: List or find ServiceCatalog objects
      description: This operation list or find ServiceCatalog entities
      tags:
      - serviceCatalog
      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/ServiceCatalog'
        '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: createServiceCatalog
      summary: Creates a ServiceCatalog
      description: This operation creates a ServiceCatalog entity.
      tags:
      - serviceCatalog
      responses:
        '201':
          description: Created
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ServiceCatalog'
        '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/ServiceCatalog_Create'
        description: The ServiceCatalog to be created
        required: true
  /serviceCatalog/{id}:
    get:
      operationId: retrieveServiceCatalog
      summary: Retrieves a ServiceCatalog by ID
      description: This operation retrieves a ServiceCatalog entity. Attribute selection is enabled for all first level attributes.
      tags:
      - serviceCatalog
      parameters:
      - name: id
        description: Identifier of the ServiceCatalog
        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/ServiceCatalog'
        '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: patchServiceCatalog
      summary: Updates partially a ServiceCatalog
      description: This operation updates partially a ServiceCatalog entity.
      tags:
      - serviceCatalog
      parameters:
      - name: id
        description: Identifier of the ServiceCatalog
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: Updated
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ServiceCatalog'
        '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/ServiceCatalog_Update'
        description: The ServiceCatalog to be updated
        required: true
    delete:
      operationId: deleteServiceCatalog
      summary: Deletes a ServiceCatalog
      description: This operation deletes a ServiceCatalog entity.
      tags:
      - serviceCatalog
      parameters:
      - name: id
        description: Identifier of the ServiceCatalog
        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:
    ServiceCategoryRef:
      type: object
      description: The (service) category resource is used to group service candidates in logical containers. Categories can contain other categories.
      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: Category 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 Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.
      required:
      - id
    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.
    ServiceCatalog:
      type: object
      description: "The root entity for service catalog management.\nA service catalog is a group of service specifications made available through service candidates that an organization provides to the consumers (internal consumers like its employees or B2B customers or B2C customers). \nA service catalog typically includes name, description and time period that is valid for. It will have a list of ServiceCandidate catalog items. A ServiceCandidate is an entity that makes a ServiceSpecification available to a catalog.\nA ServiceCandidate and its associated ServiceSpecification may be \"published\" - made visible -in any number of ServiceCatalogs, or in none."
      properties:
        id:
          type: string
          description: unique identifier
        href:
          type: string
          format: uri
          description: Hyperlink reference
        description:
          type: string
          description: Description of this catalog
        lastUpdate:
          type: string
          format: date-time
          description: Date and time of the last update
        lifecycleStatus:
          type: string
          description: Used to indicate the current lifecycle status
        name:
          type: string
          description: Name of the service catalog
        version:
          type: string
          description: ServiceCatalog version
        category:
          type: array
          items:
            $ref: '#/components/schemas/ServiceCategoryRef'
          description: List of service categories associated with this catalog
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          description: List of parties or party roles related to this category
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which the service catalog 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 Extensible name
    ServiceCatalog_Update:
      type: object
      description: "The root entity for service catalog management.\nA service catalog is a group of service specifications made available through service candidates that an organization provides to the consumers (internal consumers like its employees or B2B customers or B2C customers). \nA service catalog typically includes name, description and time period that is valid for. It will have a list of ServiceCandidate catalog items. A ServiceCandidate is an entity that makes a ServiceSpecification available to a catalog.\nA ServiceCandidate and its associated ServiceSpecification may be \"published\" - made visible -in any number of ServiceCatalogs, or in none.\nSkipped properties: id,href,lastUpdate"
      properties:
        description:
          type: string
          description: Description of this catalog
        lifecycleStatus:
          type: string
          description: Used to indicate the current lifecycle status
        name:
          type: string
          description: Name of the service catalog
        version:
          type: string
          description: ServiceCatalog version
        category:
          type: array
          items:
            $ref: '#/components/schemas/ServiceCategoryRef'
          description: List of service categories associated with this catalog
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          description: List of parties or party roles related to this category
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which the service catalog 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 Extensible 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
    ServiceCatalog_Create:
      type: object
      description: "The root entity for service catalog management.\nA service catalog is a group of service specifications made available through service candidates that an organization provides to the consumers (internal consumers like its employees or B2B customers or B2C customers). \nA service catalog typically includes name, description and time period that is valid for. It will have a list of ServiceCandidate catalog items. A ServiceCandidate is an entity that makes a ServiceSpecification available to a catalog.\nA ServiceCandidate and its associated ServiceSpecification may be \"published\" - made visible -in any number of ServiceCatalogs, or in none.\nSkipped properties: id,href"
      required:
      - name
      properties:
        description:
          type: string
          description: Description of this catalog
        lastUpdate:
          type: string
          format: date-time
          description: Date and time of the last update
        lifecycleStatus:
          type: string
          description: Used to indicate the current lifecycle status
        name:
          type: string
          description: Name of the service catalog
        version:
          type: string
          description: ServiceCatalog version
        category:
          type: array
          items:
            $ref: '#/components/schemas/ServiceCategoryRef'
          description: List of service categories associated with this catalog
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
          description: List of parties or party roles related to this category
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which the service catalog 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 Extensible name
    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':
          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 Extensible name
        '@referredType':
          type: string
          description: The actual type of the target instance when needed for disambiguation.