Page tree

Macintosh HD:Users:itsupport:Desktop:2012Files:2013Branding:TMForumUSLetterhead2013Header.jpg  

 

 

 

 

 

 

 

 

Resource Inventory Management

API Conformance Profile

 

 

Document Number <###>

V0.1

March 2017

Draft

 

 

NOTICE

Copyright © TM Forum 2017. All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to TM FORUM, except as needed for the purpose of developing any document or deliverable produced by a TM FORUM Collaboration Project Team (in which case the rules applicable to copyrights, as set forth in the TM FORUM IPR Policy , must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and TM FORUM DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

 

Direct inquiries to the TM Forum office:

240 Headquarters Plaza,

East Tower – 10 th Floor,

Morristown, NJ   07960 USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org

Table of Contents

NOTICE

Table of Contents

List of Tables

Introduction

API DESCRIPTION

RESOURCE MODEL CONFORMANCE

Customer Bill Management API MANDATORY AND OPTIONAL RESOURCES

Customer Bill resource MANDATORY AND OPTIONAL ATTRIBUTES

AppliedCustomerBillingRate resource MANDATORY AND OPTIONAL ATTRIBUTES

API OPERATIONS CONFORMANCE

Customer Bill MANDATORY AND OPTIONAL OPERATIONS

API GET FILTERING OPERATION CONFORMANCE

Filtering in Customer Bill resource

GET /customerBillManagement/customerBill

GET /customerManagement/customer/{ID}

API POST OPERATION CONFORMANCE

API PATCH OPERATION CONFORMANCE

API DELETE OPERATION CONFORMANCE

API CONFORMANCE TEST SCENARIOS

Customer resource TEST CASES

List of Tables

N/A

 

 

Introduction

The following document is the REST API Conformance for the Resource Inventory Management API.

API DESCRIPTION

The intent of this API is to provide a consistent/standardized mechanism to query and manipulate the Resource inventory.

The Resource Inventory API can be used to query the resource instances for a customer via Self Service Portal or the Call Centre operator can query the resource instances on behalf of the customer while a customer may have a complaint or a query.

The Resource Inventory API can be called by the Resource Order Management to create a new resource instance/ update an existing resource instance in the Resource Inventory.

 

 

RESOURCE MODEL CONFORMANCE

Resource Inventory Management API MANDATORY AND OPTIONAL RESOURCES

Resource Name

Mandatory or Optional

Comments

Resource

M

 

LogicalResource

O

 

PhysicalResource

O

 

Resource resource MANDATORY AND OPTIONAL ATTRIBUTES

Attribute Name

Mandatory or Optional

Comments

Id

M (in response messages)

O (otherwise)

Generated by the server and provided in the response

Href

M (in response messages)

O (otherwise)

 

Name

O

 

description

O

 

version

M (in response messages)

O (otherwise)

 

@Type

O

 

@baseType

O

 

@schemaLocation

O

 

lifecycleState

M/O

Required in response messages from the server (responses to read-GET the entity)

category

O

 

startDate

M (in response messages)

O (otherwise)

 

endDate

O

 

resourceRelationship

O

 

 

type

O

 

 

ResourceRef

O

 

resourceCharacteristic

O

 

 

name

M (if resourceCharacteristic is included)

 

 

value

M (if resourceCharacteristic is included)

 

resourceSpecificationRef

O

 

 

Id

M (if documentSpecification is included)

 

 

href

O

 

 

name

O

 

 

version

O

 

 

@type

O

 

relatedPartyRef

O

 

 

id

M (if relatedParty is included)

 

 

href

O

 

 

name

O

 

 

role

M( if relatedParty is included)

 

 

validFor

O

 

note

O

 

 

author

O

 

 

date

O

 

 

text

M( if note is included)

 

place

O

 

 

id

M( if place is included)

 

 

href

O

 

 

role

M(if place is included)

 

 

 

 

 

 

 

 

LogicalResource resource MANDATORY AND OPTIONAL ATTRIBUTES

This resource is optional and not included in the basic CONNECT certification.

 

PhysicalResource resource MANDATORY AND OPTIONAL ATTRIBUTES

This resource is optional and not included in the basic CONNECT certification.

 

API OPERATIONS CONFORMANCE

For every single resource use the following templates and define what operations are optional and what operations are mandatory.

Resource MANDATORY AND OPTIONAL OPERATIONS

Uniform API Operation

Mandatory/Optional

Comments

GET

M

GET must be used to retrieve a representation of a resource

 

POST

M

POST bust be used to create a new resource

DELETE

O

DELETE must be used to delete an existing resource

PATCH (JSON-MERGE)

O

PATCH must be used to partially update a resource

 

API GET FILTERING OPERATION CONFORMANCE

Definitions

 

Filtered Search: A filtered search can be applied using query parameters in order to obtain only the resource entities that meet the criteria defined by the filtering parameters included in the query request. Several elements can be applied to the filtered search. In that case logic, a logical AND is applied to combine the criteria (e.g.:?type=<value> &lifecycleState=<value>)

 

Filtered Data (Attribute selection): In order to apply a filter and limit the number of attributes included in the response, the GET request can include the  “ ?fields=” query parameter. Several elements can be applied to the filter. In that case, a logical AND is applied to combine the values (e.g.:?fields=category,lifecycleStatus) will provide in the response only the values assigned to attributes category and status. Attribute selection capabilities are the same for collections retrieval and individual resource queries

 

Filtering in Resource resource

Attribute name

Filtered search

First Level

Filtered search

N Level

Attribute Selection First Level

Attribute Selection N Level

Id

M

NA

M

NA

href

NA

NA

M

NA

name

M

NA

M

NA

description

M

NA

M

NA

@type

O

NA

M

NA

@baseType

O

NA

M

NA

@schemaLocation

NA

NA

NA

NA

category

O

NA

M

NA

lifecycleState

M

NA

M

NA

startDate

O

NA

M

NA

endDate

O

NA

M

NA

version

O

NA

M

NA

 

GET / resourceInventoryManagement/resource

 

Filtered Search: A filtered search can be applied using the following filtering criteria

 

 

  • resource.id : to obtain the details of a given resource id

 

  • relatedParty.id and relatedPartyRole : to obtain  the resources of a given related party playing a given role

 

  • other optional attributes as defined in the table above

 

Filtered Data: A filtered response can be requested for the following attributes using the “?fields=” query parameter

-           Any of the attributes in the first level of Resource resource definition

 

API POST OPERATION CONFORMANCE

POST to /resourceInventoryManagement /resource/

This Uniform Contract operation is used to create a Resource resource in the server.

The response to this operation must include a Location header set to /resourceInventoryManagement/ /resource /{ID} where {ID} indicates the identifier assigned by the server to the new Resource created

POST

M

 

Response Status Code 201

M

 

Other Status Codes

NA

 

 

 

The following table indicates attributes that are required to be sent when creating a new Resource resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the BODY of the POST request message:

Attribute name

Mandatory

Default

Rule

id

N

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

name

Y

 

 

description

N

 

 

@type

Y

 

 

@baseType

N

 

 

@schemaLocation

N

 

 

category

N

 

 

startDate

N

 

 

endDate

N

 

 

Version

N

 

 

relatedParty.href

N

 

Mandatory if relatedParty included

The consumer must indicate the identifier for every relatedParty assigned to the resources

resourceRelationship

N

 

Mandatory if resourceRelationship included

 

resourceSpecification

N

 

Mandatory if resourceSpecification included

resourceCharacteristic

N

 

 

place

N

 

 

note

N

 

 

 

The response from the server must include a BODY with the contents of the new resource created, filled with at least the same information elements that were included in the request and are supported by the server.

If the POST request includes optional parameters (as per the model resource definition) that are not supported by the server, then the server must reject the request (replying with a 4xx error response) indicating the parameter not supported.

The following parameters must be supported by the server when included in the request to create a new resource

  • name
  • description
  • @type
  • @baseType
  • lifecycleStatus
  • version
  • startDate
  • endDate
  • relatedParty.id
  • relatedParty.role

 

 

The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

The server must include in the BODY of the response, even if they are not included in the request, the following attributes that are mandatory in the definition of a Resource as per the resource model defined

  • id
  • href
  • @type
  • name
  • description
  • lifecycleStatus
  • category

 

 

The BODY of the response from the server must include attribute “href” (or “reference”) under each one of the entities within the Resource model that can be addressed individually and were included in the response. This applies to any of the following entities

  • relatedParty
  • resourceSpecification
  • place

 

API PATCH OPERATION CONFORMANCE

This section defines which attributes are patchable.

Since PATCH operation is optional and not included in the basic CONNECT certification this is not applicable in this conformance document.

API DELETE OPERATION CONFORMANCE

This section defines what operations can be used to delete a Resource resource.

 

Since DELETE operation is optional and not included in the basic CONNECT certification this is not applicable in this conformance document

 

API CONFORMANCE TEST SCENARIOS

This section describes the test scenarios required for the basic CONNECT certification of Resource Inventory Management API.

Test Cases must be executed in the order defined for each resource because the result from one of the scenarios will be input for the next one.

Requests must be addressed to the endpoint provided for certification, specifically they must be addressed to the URI defined by the concatenation of the {apiRoot} and the specific resource, where the {apiRoot} is defined as {serverRoot}/resourceInventoryManagement/v1 , being {serverRoot} defines the certification endpoint.

Resource resource TEST CASES

Nominal Scenarios

TC_ResInvMng_N1 – Search for resources with specific characteristics

 

TC_ ResInvMng _N2 – Filtered retrieval of resources

 

TC_ ResInvMng _N3 – Filtered Search and Filtered data response

 

Error Scenarios

TC_ ResInvMng _E1 – Unknown Resource identifier

 

TC_ ResInvMng _E2 – Invalid Request – Missing mandatory parameter

 

TC_ ResInvMng _E3 – Invalid Request – Missing parameter mandatory in context