swagger: '2.0'
info:
title: API Resource Inventory Management
description: |-
## TMF API Reference: TMF639 - Resource Inventory
### Release : 19.5 - December 2019
Resource Inventory API goal is to provide the ability to manage Resources.
### Operations
Resource Inventory API performs the following operations on the resources :
- Retrieve an entity or a collection of entities depending on filter criteria
- Partial update of an entity (including updating rules)
- Create an entity (including default values and creation rules)
- Delete an entity (for administration purposes)
- Manage notification of events
version: 4.0.0
host: serverRoot
basePath: /tmf-api/resourceInventoryManagement/v4/
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
tags:
- name: resource
- name: notification listeners (client side)
- name: events subscription
paths:
/resource:
get:
operationId: listResource
summary: List or find Resource objects
description: This operation list or find Resource entities
tags:
- resource
parameters:
- name: fields
description: Comma-separated properties to be provided in response
required: false
in: query
type: string
- name: offset
description: Requested index for start of resources to be provided in response
required: false
in: query
type: integer
- name: limit
description: Requested number of resources to be provided in response
required: false
in: query
type: integer
responses:
'200':
description: Success
headers:
X-Result-Count:
description: Actual number of items returned in the response body
type: integer
X-Total-Count:
description: Total number of items matching criteria
type: integer
schema:
type: array
items:
$ref: '#/definitions/Resource'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
post:
operationId: createResource
summary: Creates a Resource
description: This operation creates a Resource entity.
tags:
- resource
parameters:
- name: resource
description: The Resource to be created
required: true
schema:
$ref: '#/definitions/Resource_Create'
in: body
responses:
'201':
description: Created
schema:
$ref: '#/definitions/Resource'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
'/resource/{id}':
get:
operationId: retrieveResource
summary: Retrieves a Resource by ID
description: This operation retrieves a Resource entity. Attribute selection is enabled for all first level attributes.
tags:
- resource
parameters:
- name: id
description: Identifier of the Resource
required: true
type: string
in: path
- name: fields
description: Comma-separated properties to provide in response
required: false
type: string
in: query
responses:
'200':
description: Success
schema:
$ref: '#/definitions/Resource'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
patch:
operationId: patchResource
summary: Updates partially a Resource
description: This operation updates partially a Resource entity.
tags:
- resource
parameters:
- name: id
description: Identifier of the Resource
required: true
type: string
in: path
- name: resource
description: The Resource to be updated
required: true
schema:
$ref: '#/definitions/Resource_Update'
in: body
responses:
'200':
description: Updated
schema:
$ref: '#/definitions/Resource'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
delete:
operationId: deleteResource
summary: Deletes a Resource
description: This operation deletes a Resource entity.
tags:
- resource
parameters:
- name: id
description: Identifier of the Resource
required: true
type: string
in: path
responses:
'204':
description: Deleted
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/hub:
post:
operationId: registerListener
summary: Register a listener
description: 'Sets the communication endpoint address the service instance must use to deliver information about its health state, execution state, failures and metrics.'
tags:
- events subscription
parameters:
- name: data
schema:
$ref: '#/definitions/EventSubscriptionInput'
required: true
in: body
description: Data containing the callback endpoint to deliver the information
responses:
'201':
description: Subscribed
schema:
$ref: '#/definitions/EventSubscription'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
'/hub/{id}':
delete:
operationId: unregisterListener
summary: Unregister a listener
description: 'Resets the communication endpoint address the service instance must use to deliver information about its health state, execution state, failures and metrics.'
tags:
- events subscription
parameters:
- name: id
type: string
required: true
in: path
description: The id of the registered listener
responses:
'204':
description: Deleted
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method not allowed
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/listener/resourceCreateEvent:
post:
operationId: listenToResourceCreateEvent
summary: Client listener for entity ResourceCreateEvent
description: Example of a client listener for receiving the notification ResourceCreateEvent
tags:
- notification listeners (client side)
parameters:
- name: data
required: true
in: body
description: The event data
schema:
$ref: '#/definitions/ResourceCreateEvent'
responses:
'201':
description: Notified
schema:
$ref: '#/definitions/EventSubscription'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/listener/resourceAttributeValueChangeEvent:
post:
operationId: listenToResourceAttributeValueChangeEvent
summary: Client listener for entity ResourceAttributeValueChangeEvent
description: Example of a client listener for receiving the notification ResourceAttributeValueChangeEvent
tags:
- notification listeners (client side)
parameters:
- name: data
required: true
in: body
description: The event data
schema:
$ref: '#/definitions/ResourceAttributeValueChangeEvent'
responses:
'201':
description: Notified
schema:
$ref: '#/definitions/EventSubscription'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/listener/resourceStateChangeEvent:
post:
operationId: listenToResourceStateChangeEvent
summary: Client listener for entity ResourceStateChangeEvent
description: Example of a client listener for receiving the notification ResourceStateChangeEvent
tags:
- notification listeners (client side)
parameters:
- name: data
required: true
in: body
description: The event data
schema:
$ref: '#/definitions/ResourceStateChangeEvent'
responses:
'201':
description: Notified
schema:
$ref: '#/definitions/EventSubscription'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/listener/resourceDeleteEvent:
post:
operationId: listenToResourceDeleteEvent
summary: Client listener for entity ResourceDeleteEvent
description: Example of a client listener for receiving the notification ResourceDeleteEvent
tags:
- notification listeners (client side)
parameters:
- name: data
required: true
in: body
description: The event data
schema:
$ref: '#/definitions/ResourceDeleteEvent'
responses:
'201':
description: Notified
schema:
$ref: '#/definitions/EventSubscription'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
definitions:
Addressable:
type: object
description: Base schema for adressable entities
properties:
id:
type: string
description: unique identifier
href:
type: string
format: uri
description: Hyperlink reference
Any: {}
Attachment:
type: object
description: 'Complements the description of an element (for instance a product) through video, pictures...'
properties:
id:
example: 4aafacbd-11ff-4dc8-b445-305f2215715f
type: string
description: Unique identifier for this particular attachment
href:
example: 'http://host/Attachment/4aafacbd-11ff-4dc8-b445-305f2215715f'
type: string
format: uri
description: URI for this Attachment
attachmentType:
example: video
type: string
description: 'Attachment type such as video, picture'
content:
type: string
format: base64
description: 'The actual contents of the attachment object, if embedded, encoded as base64'
description:
example: Photograph of the Product
type: string
description: A narrative text describing the content of the attachment
mimeType:
type: string
description: 'Attachment mime type such as extension file for video, picture and document'
name:
type: string
description: The name of the attachment
url:
example: 'http://host/Content/4aafacbd-11ff-4dc8-b445-305f2215715f'
type: string
format: uri
description: 'Uniform Resource Locator, is a web page address (a subset of URI)'
size:
$ref: '#/definitions/Quantity'
description: The size of the attachment.
validFor:
$ref: '#/definitions/TimePeriod'
description: The period of time for which the attachment 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'
AttachmentRef:
type: object
description: 'Attachment reference. An attachment complements the description of an element (for instance a product) through video, pictures'
properties:
id:
type: string
description: Unique-Identifier for this attachment
href:
type: string
format: uri
description: URL serving as reference for the attachment resource
description:
type: string
description: A narrative text describing the content of the attachment
name:
type: string
description: Name of the related entity.
url:
type: string
format: uri
description: Link to the attachment media/content
'@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
AttachmentRefOrValue:
type: object
description: 'An attachment by value or by reference. An attachment complements the description of an element, for example through a document, a video, a picture.'
properties:
id:
example: 4aafacbd-11ff-4dc8-b445-305f2215715f
type: string
description: Unique identifier for this particular attachment
href:
example: 'http://host/Attachment/4aafacbd-11ff-4dc8-b445-305f2215715f'
type: string
format: uri
description: URI for this Attachment
attachmentType:
example: video
type: string
description: 'Attachment type such as video, picture'
content:
type: string
format: base64
description: 'The actual contents of the attachment object, if embedded, encoded as base64'
description:
example: Photograph of the Product
type: string
description: A narrative text describing the content of the attachment
mimeType:
type: string
description: 'Attachment mime type such as extension file for video, picture and document'
name:
type: string
description: The name of the attachment
url:
example: 'http://host/Content/4aafacbd-11ff-4dc8-b445-305f2215715f'
type: string
format: uri
description: 'Uniform Resource Locator, is a web page address (a subset of URI)'
size:
$ref: '#/definitions/Quantity'
description: The size of the attachment.
validFor:
$ref: '#/definitions/TimePeriod'
description: The period of time for which the attachment 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'
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
Characteristic:
type: object
description: Describes a given characteristic of an object or entity through a name/value pair.
required:
- name
- value
properties:
id:
type: string
description: Unique identifier of the characteristic
name:
type: string
description: Name of the characteristic
valueType:
type: string
description: Data type of the value of the characteristic
characteristicRelationship:
type: array
items:
$ref: '#/definitions/CharacteristicRelationship'
value:
$ref: '#/definitions/Any'
description: The value of the characteristic
'@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'
CharacteristicRelationship:
type: object
description: Another Characteristic that is related to the current Characteristic;
properties:
id:
type: string
description: Unique identifier of the characteristic
href:
type: string
format: uri
description: Hyperlink reference
relationshipType:
type: string
description: The type of relationship
'@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'
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: unique identifier
href:
type: string
format: uri
description: Hyperlink reference
name:
type: string
description: Name of the related entity.
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 Extensible name'
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
Entity:
type: object
description: Base entity schema for use in TMForum Open-APIs
properties:
id:
type: string
description: unique identifier
href:
type: string
format: uri
description: Hyperlink reference
'@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'
EntityRef:
type: object
description: Entity reference schema to be use for all entityRef class.
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':
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
Extensible:
type: object
description: Base Extensible schema for use in TMForum Open-APIs
properties:
'@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'
Feature:
type: object
description: Configuration feature.
required:
- featureCharacteristic
- name
properties:
id:
type: string
description: Unique identifier of the feature.
isBundle:
type: boolean
description: True if this is a feature group. Default is false.
isEnabled:
type: boolean
description: True if this feature is enabled. Default is true.
name:
type: string
description: This is the name for the feature.
constraint:
type: array
items:
$ref: '#/definitions/ConstraintRef'
description: This is a list of feature constraints.
featureCharacteristic:
type: array
items:
$ref: '#/definitions/Characteristic'
minItems: 1
description: This is a list of Characteristics for a particular feature.
featureRelationship:
type: array
items:
$ref: '#/definitions/FeatureRelationship'
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: '#/definitions/TimePeriod'
description: The period for which this feature relationship is valid.
LogicalResource:
type: object
description: 'Logic resource is a type of resource that describes the common set of attributes shared by all concrete logical resources (e.g. TPE, MSISDN, IP Addresses) in the inventory.'
required:
- href
- id
properties:
id:
type: string
description: unique identifier
href:
type: string
format: uri
description: Hyperlink reference
category:
type: string
description: 'Category of the concrete resource. e.g Gold, Silver for MSISDN concrete resource'
description:
type: string
description: free-text description of the resource
endOperatingDate:
type: string
format: date-time
description: A date time( DateTime). The date till the resource is operating
name:
type: string
description: A string used to give a name to the resource
resourceVersion:
type: string
description: A field that identifies the specific version of an instance of a resource.
startOperatingDate:
type: string
format: date-time
description: A date time( DateTime). The date from which the resource is operating
value:
type: string
description: the value of the logical resource. E.g '0746712345' for MSISDN's
activationFeature:
type: array
items:
$ref: '#/definitions/Feature'
description: Configuration features
administrativeState:
$ref: '#/definitions/ResourceAdministrativeStateType'
description: 'Tracks the lifecycle status of the resource, such as planning, installing, opereating, retiring and so on.'
attachment:
type: array
items:
$ref: '#/definitions/AttachmentRefOrValue'
note:
type: array
items:
$ref: '#/definitions/Note'
operationalState:
$ref: '#/definitions/ResourceOperationalStateType'
description: 'Tracks the lifecycle status of the resource, such as planning, installing, opereating, retiring and so on.'
place:
$ref: '#/definitions/RelatedPlaceRefOrValue'
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedParty'
resourceCharacteristic:
type: array
items:
$ref: '#/definitions/Characteristic'
resourceRelationship:
type: array
items:
$ref: '#/definitions/ResourceRelationship'
resourceSpecification:
$ref: '#/definitions/ResourceSpecificationRef'
resourceStatus:
$ref: '#/definitions/ResourceStatusType'
description: 'Tracks the lifecycle status of the resource, such as planning, installing, opereating, retiring and so on.'
usageState:
$ref: '#/definitions/ResourceUsageStateType'
description: 'Tracks the lifecycle status of the resource, such as planning, installing, opereating, retiring and so on.'
'@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'
Note:
type: object
description: Extra information about a given entity
properties:
id:
type: string
description: 'Identifier of the note within its containing entity (may or may not be globally unique, depending on provider implementation)'
href:
type: string
format: uri
description: Hyperlink reference
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-tmf-resourceinventorymanagement-tmf639.yml