1. REST API for Unified Inventory ManagementREST API for Unified Inventory Management
  2. Send Requests

Send Requests

Use these guidelines when sending requests to the Oracle Communications UIM REST API.

URL Structure

Access the UIM REST resources using this URL structure: 

http://hostname:port/InventoryRSOpenAPI/resourceInventoryManagement/version/logicalDevice -H "Authorization: Basic credentials"

where:

  • hostname is the URL for your UIM REST server.
  • port is the port for your UIM REST server.
  • version is the version of the API you're using, such as v1. See "Versioning".
  • credentials is the base64 encoding of a UIM user's ID and password joined by a single colon (ID:password). See "Authentication and Authorization".

For example, the URL for accessing a logical device is: 

http://hostname:port/InventoryRSOpenAPI/resourceInventoryManagement/version/logicalDevice

Versioning

This table shows the mapping between the UIM release version and the REST API version.

UIM Release REST API Version

7.4.1

v1

7.4.2

v2

7.5.0

v2

7.5.0.1 and later

v3

Supported Methods

The UIM REST API supports these HTTP methods:

HTTP Method Description
GET

Get information about UIM inventory:

  • Resources, such as logical devices and physical devices
  • Services
  • Specifications
POST

Create UIM inventory resources, such as logical devices and physical devices.
PATCH

Update UIM Inventory resources, such as logical devices and physical devices.
DELETE

Delete UIM inventory resources.

This isn't a temporary suspension or status change; it's a permanent deletion of an entire resource.

Not all endpoints support all methods.

Media Types

The UIM REST API accepts requests in application/json, application/json-patch+json, and application/merge-patch+json and sends responses in the application/json media type.

Supported Headers

The UIM REST API supports these headers in the HTTP request.

Header Description Example
Authorization The type of authorization. The UIM REST API uses Basic authorization. Authorization: Basic credentials

where credentials is the base64 encoding of a UIM user's ID and password joined by a single colon (ID:password). See "Authentication and Authorization".

Content-Type The media type of the body of the request. Required for POST requests. The UIM REST API accepts only application/json. For PATCH requests, the following can be used:

  • Merge patch: application/merge-patch+json

  • JSON patch: application/json-patch+json

Content-Type: application/json

Content-Type: application/merge-patch+json

Content-Type: application/json-patch+json
Accept-Language The IEFT language tag represents the language that your REST client understands. UIM uses this to determine which language to return error messages in. If you don't provide this header, the default of en-US is assumed. Accept-Language: fr-FR

The UIM REST API responds with these headers in the HTTP response.

Header Description Example
Authorization The type of authorization. The UIM REST API uses Basic authorization. Authorization: Basic credentials

where credentials is the base64 encoding of a UIM user's ID and password joined by a single colon (ID:password). See "Authentication and Authorization".

Content-Type The media type of the body of the response. The UIM REST API accepts only application/json. Content-Type: application/json
Content-Language The IEFT language tag represents the language of the REST response body. The default is en-US. Content-Language: fr-FR
Content-Length The size of the entity-body, in decimal number of OCTETs, sent to the recipient. In the case of the HEADmethod, the size of the entity-body that would have been sent had the request been a GET. The client can know whether it has read the correct number of bytes from the connection and can make a HEAD request to find out how large the entity-body is, without downloading it. Content-Length: 20620
ETag The identifier for a specific version of a resource. It lets caches be more efficient and saves bandwidth, because a web server doesn't need to resend a full response if the content hasn't changed. In addition, it helps prevent simultaneous updates of a resource from overwriting each other. ETag: "027d29f8e39e05039a6e5c96f1a0ada89"
Location The URI of the newly created resource. Included for POST responses for a single resource. If multiple resources are created, this header is skipped. Location: http://hostname:port/InventoryRSOpenAPI/resourceInventoryManagement/version/resource/resource-id
X-TOTAL-COUNT The total number of matching resources for a GET request. X-TOTAL-COUNT:356

Additional Parameters

The UIM REST API supports filtering, selection, sorting, expansion, and pagination parameters for some endpoints. Each endpoint described in this document lists which parameters are supported.

The additional parameters are:

Parameter type Parameter Method Description
Filtering GET

Filters the search results that are returned in GET responses. For more details, see "Filtering".

Selection fields GET, POST

Specifies the list of attributes to return as part of a partial representation of the response. Attribute selection is enabled for all first-level attributes. For example, fields=name,description.

To indicate that no resource properties should be returned, use fields=none. In this case, only the ID and HREF are returned in the resource body.

Sorting sort GET Specifies the order in which the results in the response are sorted. For example, ID, name, and so on.
Expansion expand GET Specifies the extra details to include in the response. For example, resourceRelationship.PARENT.
Depth depth GET

Specifies the level of expansion for referenced entities.

Note: Not all referenced entities can be expanded. The list of referenced entities that can be expanded is provided for each endpoint.

The default is 0, indicating that none of the referenced entities are expanded.

If expand is provided, the default depth is 1.
Pagination limit GET

Sets the maximum number of results to return in a single response. The default is 200.

The limit can't exceed 10000.
Pagination offset GET

Sets the number of results to offset the response by. The default is 0.

For example, you submit a request without setting offset and you get results 0-199, but X-TOTAL-COUNT indicates that there are 350 results. Setting offset to 200 shows the remaining results.

For example, if you made this cURL request: 

curl -X GET http://hostname:port/InventoryRSOpenAPI/resourceInventoryManagement/version/logicalDevicelifecycleSubState=unassigned&serviceLocation.name=HYD&sort=id&limit=2&offset=5&expand=resourceRelationship.INVOLVE

The response would show:

  • Only logical devices which are unassigned and which are service located in HYD (lifecycleSubState=unassigned&serviceLocation.name=HYD)
  • The details of the Involvement resourceRelationship if one exists (&expand=resourceRelationship.INVOLVE)
  • The fifth and sixth only (&limit=2&offset=5)
  • Logical devices sorted by ID (&sort=id)

The response header contains X-TOTAL-COUNT and the response body contains details of logical devices, with complete details about Involvement ResourceRelationship.

[    
   {        
      "id": "1-675003",        
      "href": "http://hostname:port/InventoryRSOpenAPI/resourceInventoryManagement/version/resource/1-675003",        
      "@type": "LogicalDevice",        
      "@baseType": "LogicalResource",        
      "name": "Email LD",        
      "description": "Email LD",        
      "version": "1",        
      "lifecycleState": "INSTALLED",        
      "lifecycleSubState": "UNASSIGNED",        
      "startDate": "2019-11-26T16:50:05.664Z",        
      "endDate": "2038-01-19T08:44:07.000Z",        
      "resourceRelationship": [            
         {                
            "type": "INVOLVE",                
            "resourceRef": {                    
            "id": "12-375019",                    
            "href": "http://hostname:port/InventoryRSOpenAPI/resourceInventoryManagement/version/resource/12-375019",                    
            "@type": "CustomObject",                    
            "@baseType": "LogicalResource",                        
            "name": "COTest",                    
            "description": "AAAAAAAA",                    
            "version": "1",                    
            "lifecycleState": "INSTALLED",                    
            "lifecycleSubState": "UNASSIGNED",                    
            "startDate": "2019-11-28T11:23:30.133Z",                    
            "endDate": "2038-01-19T08:44:07.000Z",                    
            "resourceRelationship": [                        
               {                            
                  "type": "PARENT",                            
                  "resourceRef": {                                
                     "id": "12-1",                                
                     "href": "http://hostname:port/InventoryRSOpenAPI/resourceInventoryManagement/version/resource/12-1",                                
                     "@type": "CustomObject"                            
                  },                            
                  "validFor": {                                
                     "startDate": "2019-07-29T13:45:29.286Z",                                
                     "endDate": "2038-01-19T08:44:07.000Z"                              
                  }                        
               },                        
               {                            
                  "type": "INVOLVE",                            
                  "resourceRef": {                                  
                     "id": "1-225001",                                
                     "href": "http://hostname:port/InventoryRSOpenAPI/resourceInventoryManagement/version/resource/1-225001",                                
                     "@type": "LogicalDevice"                            
                  },                            
                  "validFor": {                                
                     "startDate": "2019-11-28T11:23:30.182Z",                                
                     "endDate": "2038-01-19T08:44:07.000Z"                            
                  },                            
                  "fromRole": "CommonRole",                            
                  "toRole": "LDRole"                        
               },                        
               {                            
                  "type": "INVOLVE",                              
                  "resourceRef": {                                
                     "id": "1-675003",                                
                     "href": "http://hostname:port/InventoryRSOpenAPI/resourceInventoryManagement/version/resource/1-675003",                                
                     "@type": "LogicalDevice"                            },                            
                     "validFor": {                                
                        "startDate": "2019-12-12T14:28:11.279Z",                                
                        "endDate": "2038-01-19T08:44:07.000Z"                            
                     }                        
                  }                    
               ],                    
               "resourceCharacteristic": [                        
                  {                            
                     "name": "ebs",                            
                     "valueType": "ALPHANUMERIC",                            
                     "value": "53543"                        
                  },                        
                  {                            
                     "name": "couplingFlag",                            
                     "valueType": "ALPHANUMERIC",                            
                     "value": "1"                        
                  }                    
               ],                    
               "resourceSpecification": {                        
                  "id": "Bandwidth Profile",                        
                  "href": "http://hostname:port/InventoryRSOpenAPI/specification/Bandwidth Profile",                        
                  "name": "Bandwidth Profile",                        
                  "version": "1",                        
                  "entityType": "CustomObject",                        
                  "startDate": "2019-11-19T00:00:01.000Z",                        
                  "endDate": "2038-01-19T08:44:07.000Z"                    
               },                    
               "place": [                        
                  {                            
                     "id": "1",                            
                     "href": "http://hostname:port/InventoryRSOpenAPI/place/1",                            
                     "name": "Location1",                            
                     "@referredType": "GeographicLocation",                            
                     "role": "BATPlaceRoleSpec",                            
                     "referrerRole": "CommonRole"                        
                  }                    
               ],                    
               "relatedParty": [                        
                  {                            
                     "id": "1",                            
                     "href": "http://hostname:port/InventoryRSOpenAPI/party/1",                            
                     "name": "qq",                            
                     "role": "BATRoleSpec"                        
                  }                    
               ],                    
               "roles": [                        
                  {                            
                     "roleName": "CommonRole",                            
                     "roleType": "FUNCTION"                        
                  }                    
               ]                
            },                
            "validFor": {                    
               "startDate": "2019-12-12T14:28:11.279Z",                     
               "endDate": "2038-01-19T08:44:07.000Z"                
            }            
         }        
      ],        
      "resourceSpecification": {            
         "id": "Email_Server",            
         "href": "http://hostname:port/InventoryRSOpenAPI/specification/Email_Server",            
         "name": "Email_Server",            
         "version": "1",            
         "entityType": "LogicalDevice",            
         "startDate": "2019-11-26T00:00:01.000Z",            
         "endDate": "2038-01-19T08:44:07.000Z"        
      },        
      "networkLocation": {            
         "id": "HYD",            
         "href": "http://hostname:port/InventoryRSOpenAPI/place/HYD",            
         "name": "HYD",            
         "@referredType": "PropertyLocation"        
      },        
      "serviceLocation": {            
         "id": "HYD",            
         "href": "http://hostname:port/InventoryRSOpenAPI/place/HYD",            
         "name": "HYD",            
         "@referredType": "PropertyLocation"        
      },        
      "deviceIdentifier": "HYD-Mail-DI"    
   },    
   {        
      "id": "1-675004",        
      "href": "http://hostname:port/InventoryRSOpenAPI/resourceInventoryManagement/version/resource/1-675004",        
      "@type": "LogicalDevice",        
      "@baseType": "LogicalResource",        
      "name": "HYD-DI1",        
      "version": "1",        
      "lifecycleState": "INSTALLED",        
      "lifecycleSubState": "UNASSIGNED",        
      "startDate": "2019-11-29T11:53:47.755Z",        
      "endDate": "2038-01-19T08:44:07.000Z",        
      "resourceSpecification": {            
      "id": "Packet Network Device",            
      "href": "http://hostname:port/InventoryRSOpenAPI/specification/Packet Network Device",            
      "name": "Packet Network Device",            
      "version": "1",            
      "entityType": "LogicalDevice",            
      "startDate": "2019-11-19T00:00:01.000Z",            
      "endDate": "2038-01-19T08:44:07.000Z"        
   },        
   "networkLocation": {            
      "id": "HYD",            
      "href": "http://hostname:port/InventoryRSOpenAPI/place/HYD",            
      "name": "HYD",            
      "@referredType": "PropertyLocation"        
   },        
      "serviceLocation": {            
         "id": "HYD",            
         "href": "http://hostname:port/InventoryRSOpenAPI/place/HYD",            
         "name": "HYD",            
         "@referredType": "PropertyLocation"        
      },        
      "deviceIdentifier": "HYD-DI1",        
      "deviceInterfaces": "http://hostname:port/InventoryRSOpenAPI/resourceInventoryManagement/version/logicalDevice/1-675004/deviceInterfaces"    
   }
]

Filtering

The filtering parameter supports these operators, in this order of precedence.

  1. CONTAINS_IGNORE_CASE
  2. BEGINS_WITH_IGNORE_CASE
  3. ENDS_WITH_IGNORE_CASE
  4. NOT_EQUALS_IGNORE_CASE

Note:

The OR operation isn't supported.

REST Criteria Operator UIM Criteria Operator Operator Literal URL Encoded Form Example
= EQUALS_IGNORE_CASE .eq %3D%3D lifecycleState=UNASSIGNED lifecycleState==UNASSIGNED lifecycleState%3D%3DUNASSIGNEDlifecycleState.eq=UNASSIGNED
<= LESS_THAN_EQUAL .lte %3C%3D rangeTo.lte=1000000100 rangeTo<=1000000100 rangeTo%3C%3D1000000100
>= GREATER_THAN_EQUAL .gte %3E%3D rangeFrom.gte=1000000001 rangeFrom>=1000000001 rangeFrom %3E%3D1000000001
! NOT_EQUALS_IGNORE_CASE regex( with !) ! vendorPortName.regex=!oracle vendorPortName*=!oracle
^ BEGINS_WITH_IGNORE_CASE(7), .regex ( with ^) %5E vendorPortName.regex=^oracle vendorPortName*=^oracle vendorPortName*=%5Ecisco
$ ENDS_WITH_IGNORE_CASE(8), .regex ( with $) "%24" vendorPortName.regex=oracle$ vendorPortName*=oracle$ vendorPortName*=oracle%24
^.* CONTAINS_IGNORE_CASE(9), %5E.* vendorPortName.regex=^.*oraclevendorPortName*=^.*oracle vendorPortName*=%5E.*oracle

Characteristics

The UIM REST API POST request supports these character value types.

Design Studio Type REST Character Value-Type Mapping
String/double/decimal/float/time ALPHANUMERIC
Integer/long NUMERIC
EntityLink OBJECT
boolean BOOLEAN
date DATE
jpql ALPHANUMERIC
datetime DATE
time ALPHANUMERIC
url URL
ENUM ALPHANUMERIC

Example 1: String Characteristic

"resourceCharacteristic": [
   {            
      "name":
      "model",           
      "valueType": "ALPHANUMERIC",            
      "value": "WXC12234"        
   }  
]

Example 2: CustomObject EntityLink Characteristic 

{            
   "name": "elChar",           
   "valueType": "OBJECT",
   "value": {               
      "id": "12-1",                
      "@type": "CustomObject"           
   }        
}

Example 3: Place EntityLink Characteristic 

{            
   "name": "site",           
   "valueType": "OBJECT",
   "value": {               
      "id": "Geographic_Site_Id_001",
      "@referredType": "GeographicSite"           
   }        
}