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 |
v3 |
Supported Methods
The UIM REST API supports these HTTP methods:
| HTTP Method | Description |
|---|---|
GET |
Get information about UIM inventory:
|
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:
|
|
Accept-Language |
The IEFT language tag representing 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 representing the language that 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.
- CONTAINS_IGNORE_CASE
- BEGINS_WITH_IGNORE_CASE
- ENDS_WITH_IGNORE_CASE
- 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"
}
}