Introduction & Overview

The Oracle Communications Diameter Signaling Router Machine to Machine Interface

This Application Programming Interface (API) document describes the Machine to Machine Interface (MMI) for the Oracle Communications Diameter Signaling Router (OC-DSR, often shortened to simply DSR). The DSR MMI is a RESTful (Representational State Transfer) interface providing access to a broad range of Operations, Administration, and Maintenance (OAM) services that clients use to configure and manage the DSR. This document is the comprehensive API reference guide to the RESTful services the DSR makes available to clients through the DSR MMI.

General URI Format for DSR MMI Requests

The general format of a Uniform Resource Identifier (URI) used to send an MMI request to the DSR is:

https://{target}/mmi/dsr/{version}/{area}/{resource}[/{instance}][/{sub-resource}[/{sub-instance}]]*[/{attribute or action}]

where

• {target} is the IP address or FQDN (Fully Qualified Domain Name) of the OAM server receiving the MMI request.
• {version} is the MMI API version number. If the MMI client specifies a version that is not supported by the DSR, HTTP status code 404 is returned in the response.
• {area} is the functional area that includes the desired MMI API (areas are defined in the next paragraph).
• {resource} is the specific DSR resource being accessed - with DSR, the resource generally equates to a Managed Object (MO).
• {instance} is necessary when the client is accessing a specific instance of a resource; {instance} is the unique identifier for the resource record, and is often the instance's name attribute (although some resources use a different attribute as the unique identifier, particularly when the resource's instances don't have names).
• {sub-resource} is the specific sub-resource within the resource associated with the requested operation. It could consist of one or more tokens (e.g., /db/backup).
• {sub-instance} is only necessary when the client is accessing a specific sub-instance of a sub-resource; typically the {sub-instance} value is the name of a specific sub-resource; {sub-instance} should only appear when following a {sub-resource}.
• {attribute or action} is only necessary when the client is performing an action on a specific instance. {attribute or action} could be name of an attribute being read or updated (e.g., the administrative state) of an instance or sub-instance. Note: in this context, {action} is not one of the standard HTTP actions, but is instead one of the specific actions supported by the resource or sub-resource.

DSR MMI clients use Secure Sockets Layer (SSL) connections (HTTPS) to communicate with the target DSR.

APIs are Grouped by Functional Area

DSR MMI APIs are grouped by functional area and, as shown in section General URI Format for DSR MMI Requests, the area is one segment of the URI sent to the DSR. MMI APIs are available for the following areas of DSR functionality:

• Client Authentication (area: auth) - MMI security - authentication, authorization, and audit
• Bulk Configuration (area: bulk) - bulk export and import of system configuration
• System Administration (area: admin) - DSR network administration functions
• System Monitoring (area: mon) - access to system processes, logs, statistics, and measurements
• Topology Configuration and Management (area: topo) - insert, edit, delete, retrieval, and management of system topology resources; note that the topo area only covers management of server and network resources; application-specific resources are part of other areas (e.g., diameter)
• Core Diameter (area: diameter) - configuration establishing the DSR as a Diameter Relay Agent, including IP Front End (IPFE) behavior
• Non-Specific (area: all) - general APIs that span multiple areas of functionality

Within this API documentation, resource descriptions are organized by area, then alphabetically by the individual resource name within each area. A few resources do not have a Request block for a particular action (e.g., /diameter/mpprofileassignments GET; /mon/measurements/budget GET). This is not a mistake or oversight. In these cases, there are no valid query parameters for the API, and the Request block is simply omitted.

Both Network and Site OAM Servers Provide MMI Access

A DSR is a collection of cooperating servers arranged in a three-tiered hierarchical topology. MMI functionality is available at the top two levels of the hierarchy:

• Network - the administrative domain consisting of all DSR Sites, managed using highly available (HA) clusters of Network Operations, Administration, and Maintenance (NOAM) servers. Network-scoped functionality is hosted in this top level of the topology hierarchy and is referred to as the A-Level.
• Site - a site-level administrative domain, managed using clusters of HA Site Operations, Administration, and Maintenance (SOAM) servers. Operations performed at the SOAM are scoped to the specific SOAM (all SOAM servers in the HA cluster, plus all sub-tending C-level servers - note that these servers may not all reside at the same physical location). Site-scoped functionality is hosted in the middle layer of the topology hierarchy and is referred to as the B-Level.

The bottom level of the topology hierarchy, the C-Level, is reserved for application-level servers (DA-MPs, IPFEs, SBRs, SS7-MPs), which do not provide any administrative access. DSR MMI functionality is only available on the OAM servers.

Adding or editing a resource instance is done at either the NOAM or the SOAM, but not both. The documentation for each resource identifies whether the NOAM or SOAM is the target of an MMI request for that resource. Note that, for some resources configured at the NOAM, it is possible to retrieve the configuration - but not change it - at an SOAM. Also, status/monitoring resources like measurements, KPIs, and alarms can be retrieved at both the NOAM and SOAM. The data returned by the target OAM server is scoped to that server.

MMI Requests Are Sent to Active OAM Servers

Whenever OAM servers are deployed in High-Availability (HA) clusters, it is the server holding the HA role of active that must receive an MMI request. If a Virtual IP (VIP) is configured for the OAM cluster, requests sent to that VIP are automatically handled by the active OAM server. If an OAM server is standing alone (not part of an HA cluster), it is by default considered the active server and should be the target of client MMI requests.

RESTful Operation Overview

The DSR configuration is managed through Create, Retrieve, Update, and Delete (CRUD) actions on instances of the various resource types built into the DSR. A particular type of resource (e.g., Server, Network Element, Peer Node, Traffic Throttle Group) is also known as a Managed Object (MO), and a specific instance of a resource is known as an MO instance. Throughout this document, the term MO is used to refer either to the type or to a particular instance of a type. The intended usage should be clear from the context.

The CRUD operations are implemented using standard HTTP verbs:

• HTTP POST is used to Create a new resource instance.
• HTTP GET is used to Retrieve one or more resource instances.
• HTTP PUT is used to Update a resource instance.
• HTTP DELETE is used to Delete a resource instance.

The following sections provide a brief overview of how the CRUD operations work through the MMI using simple examples. In these examples, a simplified version of the RESTful result structure is used for illustration purposes. Refer to the schema definition in the API description for a particular resource for a complete response definition specific to that resource.

Create Pattern

To create a new instance of a resource, POST it to the collection. POST returns a response populated with the identifier of the newly created resource instance. In most cases, the resource instance identifier is simply the client-provided name of the resource. For resources that do not have a simple name field, or for which the name field is not required to be unique, a unique identifier is constructed and returned.

For example:

POST /resource/ + BODY { "name":"newInstance", "description":"an example" }

Returns the new resource ID:

"data":"newInstance", "messages":[], "links":[], "status":true

Update and Delete Patterns

To update an instance of a resource, the PUT operation is used. To delete an instance, the DELETE operation is used.

There are a few common reasons why an update operation might fail:

1. System updates have been disabled.
2. The update data is incomplete or is some other way invalid.
3. The MMI user account does not have permission to perform the requested operation for the specified resource.
4. The server is currently overloaded and cannot handle a new request.

Any failure explanation(s) are returned in the messages portion of the response.

Use of Natural Identifiers

Most of the DSR MMI resource APIs use the natural identifier (typically the name field) for a resource instance. For example, the /topo/servers resource uses the server name as its natural identifier. However, in certain cases, where there is no natural identifier, a unique identifier is generated. The /route resource, for example, has no natural identifier, so one is generated at the time a new route is created.

The documentation for each resource defines what property is used as the identifier (as returned in a POST response).

Idempotent GET/PUT

A GET of a resource instance, followed by a PUT of the same resource instance, leaves the resource essentially unchanged.

Note that occasionally there are fields in a resource schema that are described as computed. These fields are always ignored on PUT. Computed fields are also ignored on initial creation requests using POST.

Some fields are read-only, and are identified as such in the JSON schemas. If included by the client in a PUT request, read-only field values are ignored by the DSR.

Some fields are not updatable. These fields must be set on initial creation via POST, and are ignored on subsequent updates.

Structured Response

Unless stated otherwise, operations place returned results in a structured container of the form:

• data (optional) - If the operation returns data, the data is placed in the data portion of the result.
• messages (optional) - If the operation returns any warnings, errors, status, or other informational data, they are placed in the messages portion of the result.
• links (optional) - If the operation returns links supporting or suggesting follow-up resources or actions, they are placed in the links portion of the result.
• status - true on success, false on failure. If false, the messages portion of the response provides details.

HTTP Status Codes

DSR operations available through the MMI API are atomic, unless stated otherwise for a specific resource. If a configuration operation does not complete successfully, the DSR is left in its original state. The RESTful operations generally available for resources, and possible return codes for each, are:

• GET - retrieve one or more items from a collection, or retrieve just a single item identified by a unique name/id
  • 200 - operation successful
  • 400 - bad request
  • 401 - not authenticated
  • 403 - not authorized
  • 404 - item not found/API version not supported
  • 429 - too many requests
• POST - insert a new item into a collection
  • 201 - operation successful - item created
  • 202 - request accepted - operation in progress
  • 400 - bad request
  • 401 - not authenticated
  • 403 - not authorized
  • 404 - API version not supported
  • 500 - internal server error
• PUT - update a specific, existing item in a collection
  • 200 - operation successful
  • 202 - request accepted - operation in progress
  • 400 - bad request
  • 401 - not authenticated
  • 403 - not authorized
  • 404 - API version not supported
  • 409 - resource state conflict
  • 500 - internal server error
• DELETE - delete a specific item from a collection
  • 204 - operation successful (no content is returned from a delete operation)
  • 400 - bad request
  • 401 - not authenticated
  • 403 - not authorized
  • 404 - API version not supported
  • 409 - resource state conflict
  • 500 - internal server error

General Behaviors

This section defines general behaviors of the DSR Machine to Machine Interface.

1. Read-only attributes - Most resources have one or more read-only attributes, and these are identified in the JavaScript Object Notation (JSON) schemas by the readOnly property. Read-only attributes are always returned in any GET response. Clients should not include read-only attributes in the JSON data accompanying a POST or PUT request, as the presence of read-only values never results in a DSR state change. If a POST or PUT request does include a read-only attribute value that has the correct data type (per the JSON schema), the DSR ignores the value and processes the request as if the read-only attribute were not present. If, however, a POST or PUT request includes a read-only attribute value whose data type is not correct, the DSR returns an error response. The client should fix the data type - or remove the attribute from the JSON data entirely - and re-send the request.

2. Simultaneous client interactions - If two or more DSR clients attempt to modify the same resource at the same time, the last-in-time request received by the DSR is the one with final impact on the state of the DSR. No error response is sent to the other clients, but the changes requested by those clients are overwritten as a result of the request received from the last-in-time client, if there is any overlap between the requests. For example, if client #1 updates the configuration of a resource instance, but client #2 subsequently deletes that same resource instance, the instance is deleted and client #1 receives no notification that the instance it just updated has been deleted.

3. Filtering and sorting - Generally speaking, query parameters for a collection GET operation can be used to tailor the returned results to a select subset of the collection. In this version of the API, the only tailoring somewhat widely supported is paging - returning N items beginning at a specified offset into the collection. In general, the following are not supported operations: 1) filtering results by an arbitrary named attribute, and 2) sorting the results by any arbitrary attribute. There are a few APIs - namely, for status sub-resources - that support this kind of attribute-based filtering. These are so indicated in the individual resource documentation.

4. Paging - Paging parameters for a collection GET operation are used to return a client-defined number of resource instances, beginning at a specified offset. In this version of the API, only resources in the Core Diameter (/diameter) area support paging. For the Core Diameter area, if paging query parameters are not supplied in the request, the number of records returned is limited to a default page size, and always begins with the first record in the configuration. If paging query parameters are supplied in the request, a success response is returned only if the requested number of instances is less than or equal to the default page size. The success response contains links for the next and previous set of records, and a message indicating the count of remaining records, when applicable. The default page size - the number of resources returned by the DSR in a GETALL request when the client does not specify a desired count in the request - is defined by the DSR and is currently set to 1000.

5. Default attribute values - In general, DSR provides no default value for an attribute when POSTing a new instance to the configuration. If no value is provided in the client request for an attribute that is required, the POST fails and a specific error message is returned. If no value is supplied by the client for an attribute that is not required, that attribute may or may not have a value in the configuration, depending on the specific behavior of the resource being configured.

6. Data validation - The data for all PUT and POST operations is validated both for syntactic and semantic correctness before the operation is allowed to proceed. If any validation errors occur, the response has a status of false, and the messages portion of the response contains one or more messages documenting the specific error details. Any unexpected operation failures also result in a status of false being returned, along with details in the messages portion of the response.

7. Attempting to delete a resource instance that doesn't exist - If a client attempts to delete a resource instance whose unique identifier is not present in the DSR's configuration, the DSR responds with either a 400 or 409 HTTP status code, depending on the resource type.

8. Handling of invalid query parameters - In this release of the DSR software, the error handling capability for invalid query parameters is limited. If a client sends a query string with one or more invalid query parameter values, the DSR's response to the request is not guaranteed to be expected.

MMI Security

With very few exceptions, access to any of the RESTful APIs supported by the DSR requires authentication. Section The Client Authentication Area describes the specifics of the authentication mechanism. In short, a client must obtain a token from the DSR by providing valid credentials. Once the client has the token, it can access any DSR MMI resource that requires authentication by providing the token in the header of the HTTP request.

Each individual resource action (GET, POST, etc.) described in this API specification includes a "secured by" designation. If the resource action requires authenticated access, this designation is "Secured by x-other". If the resource can be accessed by a client without authentication, the designation is "Secured by none". If the resource can be accessed with or without authentication, both "Secured by x-other" and "Secured by none" are present.

Note that in this release of the API, there are only two resources that can be accessed without authentication - and both of those can also be accessed with authentication.

Any resource action that includes "Secured by x-other" is rendered with a lock icon preceding the action name.

Examples

Retrieving Resource Instances: GET

There are many ways an MMI client can create the HTTP request sent to the DSR. One common tool is curl, which is available in many languages and supports several internet protocols, including HTTPS. The following example illustrates use of curl from a command line to GET all of the Capacity Configuration Sets (/diameter/capacityconfigurationsets) configured at the target DSR (here represented by 'localhost'):

curl --header 'X-Auth-Token:EFEFC54B7F19EE5B75DF' --request GET 'https://localhost/mmi/dsr/v1.0/diameter/capacityconfigurationsets'

The structured response returned by the DSR contains the following JSON data structure:

{ "data": [ { "configurationLevel": "0", "convergenceTime": 1000, "ingressMpsMajorAlarmThreshold": 80, "ingressMpsMinorAlarmThreshold": 50, "maxIngressMps": 10000, "name": "Default", "reservedIngressMps": 0, "reservedIngressMpsAbatementTime": 2000 } ], "links": {}, "messages": [], "status": true }

The value of true for "status" indicates that the request was successfully processed, without any errors. In this case, there is only a single Capacity Configuration Set present in the DSR configuration, so only one instance appears in the array in the "data" section of the response.

Inserting a Resource Instance: POST

When inserting a new resource instance into the DSR configuration, the client must supply a JSON data structure, in accordance with the schema defined for the resource being inserted. In the following example, a Capacity Configuration Set (/diameter/capacityconfigurationsets) is added to the DSR represented by 'localhost' using curl from a command line:

curl --header 'X-Auth-Token:D2D588AE818739218A33' --request POST --data '{"name": "CapacityConfigurationSet1", "ingressMpsMajorAlarmThreshold": 80, "maxIngressMps": 10000, "reservedIngressMpsAbatementTime": 2000, "ingressMpsMinorAlarmThreshold": 50, "convergenceTime": 1000, "reservedIngressMps": 0}' 'https://localhost/mmi/dsr/v1.0/diameter/capacityconfigurationsets'

Assuming all supplied data is valid and the Capacity Configuration Set is successfully added to the configuration, the response from the DSR is:

{ "data": { "id": "CapacityConfigurationSet1", }, "links": {}, "messages": [], "status": true }

The Client Authentication Area

(area: "auth")

Authentication

The auth area provides the tokens (/auth/tokens) interface for client authentication. Before performing any other operation with DSR, the client must first obtain an authentication token using the tokens interface.

The client provides credentials to identify itself, and if the credentials are successfully authenticated, DSR returns a valid token. The client then embeds the token in subsequent MMI calls using the X-Auth-Token header.

Tokens typically expire after two hours. It is the responsibility of the client to request a fresh token before or when the previous token expires. A valid token can also be used to authenticate a client, so it is possible to replace an unexpired token with a new one that has a fresh two-hour lifetime.

A token created on any OAM server is immediately usable on that server, and becomes usable on all the OAM servers in the DSR topology after a short propagation delay (typically 3-5 seconds).

It is recommended that MMI clients re-use a valid token for up to its full two hour lifetime, rather than request a new token for each MMI non-authentication request. Requesting a new token for each non-authentication request effectively doubles the number of MMI requests the client sends to the DSR. Clients may observe decreased MMI responsiveness if a new token is requested for every non-authentication MMI request, compared to getting a token and using it for all subsequent MMI requests within its two hour lifetime.

Authorization

The token grants the bearer the same capabilities as the original MMI authentication credentials. GUI and MMI share the same user accounts and permissions database (GUI group) settings. Note that some user accounts may be limited to GUI-only or MMI-only access.

Audit Trail

All uses of a token are logged to the system security log (also shared with the GUI). Token creation and expiration generate events in the system event log.

The Topology Configuration and Management Area

(area: "topo")

The topo area provides RESTful interfaces enabling topology configuration and management for:

• Servers
• Server Groups
• Resource Domains
• Places
• Place Associations
• Network Elements
• Networks
• Network Routes
• Network Devices
• Network Service Paths
• DSCP Port Rules
• DSCP Interface Rules

The topo area covers general server/network/DSR topology configuration - the higher-level configuration that is necessary to support the mission of a DSR. Diameter-specific configuration is not part of the topo area - that is covered by the diameter area for core routing configuration, and several of the other areas, which are specific to the various applications DSR supports.

Management Services

The /topo/servers and /topo/networkelements resources provide the following management and control facilities:

• Server Status - A general summary status report for a server
• Server Management - Server management - reboot and ntpsync
• Server DB Status and Management - Database status and management (backup/restore) for a server
• Server HA Status and Management - High Availability status and management (roles) for a server
• Server Provisioning Status and Management - Data Provisioning status and management for a server
• Server Replication Status and Management - Data Replication status and management for a server
• Server Application Status and Management - Application status and management for a server
• Router Monitoring Status and Management - Gateway Router monitoring management for a network element

In general, a status request returns the current state of the resource (using GET), while a management request updates the resource (using PUT) to change its status.

The Bulk Configuration Area

(area: "bulk")

The bulk area supplies a bulk export/import facility (/bulk/configurator). The bulk export is used to extract configuration information from a DSR in bulk. Bulk export is always done per area, although multiple areas can be specified in a single MMI request. All resources included in the specified area(s) are exported together, and the results are written to an XML file located on the OAM server that received the request. Bulk export of individual resources is not supported.

Bulk import is limited to just the comagent, diameter, fabr, rbar, topo and vstp area, and is used to deploy the configuration associated with the topology rapidly for one or more DSR sites. The bulk import facility can only be used to insert (POST) configuration instances; it cannot be used to edit or delete configuration.

The import operation is non-atomic; the import operation returns a result code and a list of all the import failures providing details on why the import operation failed. At the end of the import operation, any objects that were successfully configured remain configured; any objects that failed configuration are not configured. It is up to the client to interpret any error messages and take whatever remedial action is necessary to ensure a complete and correct topology configuration.

Some common reasons why an object may fail to be successfully imported are:

1. The object is already in the configuration (duplicate id).
2. The syntax of the XML specification for the object is incorrect (syntax).
3. Internal validation rules block the creation of the object (semantic checks).
4. The server is overloaded and cannot handle a new request.

Managed objects cannot be edited or deleted using the import interface. Rather, the individual resource MMI APIs must be used (e.g., DELETE /topo/servers/{servername}).

Bootstrapping

Whenever a new server is created using either the bulk import operation or the topology server insert (POST), the new server needs to be bootstrapped to activate it and enable it to become part of the functioning system topology. Depending on how much configuration was performed on the bare metal or on the new VM by an infrastructure manager, the bootstrap may have more or less to do. The bootstrap is performed by invoking the /topo/servers/{servername}/bootstrap operation directly on the new server, passing a list of bootstrap options. Shortly after the bootstrap has completed, the other servers in the topology should recognize the new server, and the new server is configured and prepared for operation. The progress of the server can be monitored using the server status interface (/topo/servers/{servername}/status).

The System Administration Area

(area: admin)

The system administration (admin) area allows an MMI client to set up the following for the DSR network:

• Domain Name System (DNS) configuration for communication by the DSR with remote servers
• Security Certificates for secure communication between the DSR and remote servers
• Secure File Transfer Protocol (SFTP) User configuration
• Simple Network Management Protocol (SNMP) Trap manager configuration

This area also provides an API for clients to retrieve the DSR software version identifier for the software version currently running on the target OAM server.

The System Monitoring Area

(area: "mon")

The system monitoring (mon) area provides access to:

• Measurements - Historical store of system counters
• Key Performance Indicators - Point in time indicators of system health
• Alarms - Currently active alarms
• Processes - System Process resource impacts
• Tasks - Recently run or running background tasks
• Periodic Tasks - The schedule of regularly executing tasks

The system monitoring interfaces are primarily read-only, and are used to obtain status information about the system.

Scoped Data

In general, when data is requested via MMI from an OAM server, the data received is scoped to that OAM server. Therefore, a request made to the NOAM, which is at the top (A) level of the hierarchy, returns data for all servers in the DSR topology, while a request made to an SOAM (B-level) only returns data scoped to that SOAM Server Group - all SOAM servers in the HA cluster, plus all sub-tending C-level servers.

Some data (notably some measurements and alarms) is scoped to an SOAM, and is not available at the network (NOAM) level. Requests to retrieve SOAM-scoped data must be made to the specific SOAM.

Time-Ordered Data

The /measurements and /alarms services provide access to time-ordered datasets. Requests can be restricted to a specific time range (often useful in post-mortem problem analysis). If no time range is specified, the /measurements resource returns the most current measurements data set, while the alarms service returns all the currently active alarms.

Rate-Limited Data

The /measurements resource is rate-limited. To ensure that the processing costs associated with creating a measurement report do not exceed the available OAM server resources, each query of measurement data counts against a budget allocated for the request interval.

1. At the start of each interval (an even 5 minute boundary), the request budget is reset.
2. Each measurement query in the request interval subtracts from the budget.
3. If a request is made while the budget is empty, the request is rejected.

The /measurements/budget resource can be used to determine the remaining available budget for the current request interval. Each measurement request returns the remaining budget and the cost of the request.

A measurement report cost is calculated based on the following rules:

• Each cell of reported data has a cost of one unit.
• An arrayed measurement with N populated subindexes has a cost of N units.
• Each reported time-interval multiplies the cost by the number of intervals.
• Each reported server multiplies the cost by the number of servers.

Applying these rules, a hypothetical measurement report has a report cost of 15,000,000 if it 1) has arrayed measurements with 15,000 subindexes; 2) spans 100 servers; and 3) includes 10 time-intervals.

Clients typically do not need to keep track of the measurement report budget. Each OAM server should be configured with a budget large enough to support most typical measurement report requests. If a request is submitted after the budget for an interval has been exhausted, the client receives an HTTP response of 429 - too many requests. The measurement report request should be re-submitted later.

The Core Diameter Area

(area: "diameter")

The diameter area includes all of the MMI APIs required to configure a DSR to be a Diameter Relay Agent (DRA). Diameter routing entities like Local Nodes, Peer Nodes, Connections, Route Groups, and Route Lists are all part of the diameter area. Also included is IPFE configuration, which is used to load balance Diameter Connections across a set of DA-MPs.

The discussion of the various patterns (create, update, delete) given in the Introduction & Overview section is highly relevant to the diameter area. Individual Managed Objects and collections of MOs are accessed by the client using the APIs defined for each core Diameter resource. Any operation that completes successfully returns a 2XX HTTP code, while unsuccessful operations return a 4XX HTTP code.

The All Area

(area: all)

The all area includes resources that span functional areas. For this release of the API, the object versioning interface is the only resource included in all.

Overview of Object Versioning

DSR supports the concept of object versioning, so that an MMI client can easily track the configuration changes that are made to the DSR. The configuration level is an integer value that gets incremented each time a change is made, and the configuration level integer exists 1) for the OAM server as a whole to track all changes made to the configuration database, and 2) for each individual resource type to track changes made to the instances of that particular resource.

An MMI client requests the current configuration level data from an OAM server, and uses that data to identify where changes have been made since the last time the client had a current view of the configuration. Clients use the Configuration Levels (/all/configurationlevels) URI to retrieve the current configuration level data, and the response to this request returns the server-scoped integer value (identified by "consolidated" in the response data) as well as the various resource-specific integer values for all resources supported by the OAM server (identified by the specific resource name).

Object versioning via configuration level is not yet included by all the functional areas within the DSR MMI API specification. For this release, only the diameter area supports configuration level.

The Fabr Area

(area: "fabr")

The fabr area includes all of the MMI APIs required to configure a Full Address Based Resolution application. Full Address Based Resolution entities like Supported Applications, Routing Exceptions, Default Destinations, Address Resolutions, and System Options are all part of the fabr area.

The discussion of the various patterns (create, update, delete) given in the Introduction & Overview section is highly relevant to the fabr area. Individual Managed Objects and collections of MOs are accessed by the client using the APIs defined for each core Fabr resource. Any operation that completes successfully returns a 2XX HTTP code, while unsuccessful operations return a 4XX HTTP code.

The ComAgent Area

(area: "comagent")

The comagent area includes all of the MMI APIs required to configure Communication Agent (ComAgent) including infrastructure features and services for enabling inter-server communication. ComAgent entities like Remote Servers, Connection Groups and Routed Services are all part of the ComAgent area.

The discussion of the various patterns (create, update, delete) given in the Introduction & Overview section is highly relevant to the ComAgent area. Individual Managed Objects and collections of MOs are accessed by the client using the APIs defined for each core ComAgent resource. Any operation that completes successfully returns a 2XX HTTP code, while unsuccessful operations return a 4XX HTTP code.

The Radius Area

(area: "radius")

The radius area includes all of the MMI APIs required to configure entities like Ingress Status Server Configuration Sets, Shared Secret Configuration Sets, Message Conversion Configuration Sets, Message Authenticator Configuration Sets, NAS Nodes, and Radius Options are all part of the radius area.

The discussion of the various patterns (create, update, delete) given in the Introduction & Overview section is highly relevant to the radius area. Individual Managed Objects and collections of MOs are accessed by the client using the APIs defined for each core Radius resource. Any operation that completes successfully returns a 2XX HTTP code, while unsuccessful operations return a 4XX HTTP code.

The Scef Area

(area: "scef")

The scef area includes all of the MMI APIs required for SCEF configuration which includes the following resources.

• NIDD Configuration Sets: A set of configurations that apply to NIDD call flows.
• APN Configuration Sets: A set of configurations that are associated to an APN, The APN is associated to a SCS/AS Profile.
• Monitoring Event Configuration Sets: A set of configurations for SCEF Monitoring Events.
• Device Triggering Configuration Sets: A set of configurations for Device Triggering to create a SCS/AS.
• SCS Application Servers: Service Capability Server (SCS) enables Applications to access and use functionality provided by Service Components over standardized interfaces (APIs).
• System Options: SCEF related user configurable Options.
• Access Control Lists: A set of configurations to support multi tenancy Access Control, DRMP and Flow/Overload Control during notification callback.
• Access Control Rules: A set of configurations to create an Access Control Rule.
• Access Control Associations: This is used to associate the Rules with an Access Control List.

The Eir Area

(area: "eir")

The eir area includes all of the MMI APIs required to configure the EIR application. EIR application provides a mechanism that will allow the network operators to prevent stolen or disallowed handsets from accessing the network.

The Common Security Area

(area: "commonsecurity")

The commonsecurity area includes all of the MMI APIs required to configure the CCNDC Mapping and Neighboring Countries. The Common Security application provides a mechanism that to add and remove tables for CCNDC Mapping and Neighboring Countries.

Change Log

API Version v4.2 ( DSR Release 8.5.0.2.0_92.7.0 )

Backward Compatible Changes

• Added new attribute for Message Copy Configuration Sets in Options API (diameter/options).
• Added new attribute for Rf Message Copy Feature Enabled in Options API (diameter/options).
• Added new attributes - AAA Route List, MPN Route List and UMF Route List in Options API (diameter/options).
• Added new resource Rf Message Copy (diameter/rfmessagecopy).
• Initial Creation for area: Radius.
• Added Bulk Export and Import support for all Radius managed objects.
• Added new resource SMS Proxy Options(vstp/smsproxyoptions).
• Added new resource SMS Proxy SMSC Status(vstp/smscstatus).

Non-Backward Compatible Changes

• None

Non-Interface Changes

• None

API Version v4.1 ( DSR Release 8.5.0.0.0_90.11.0 )

Backward Compatible Changes

• Added new resource Country Latitude Longitude (/commonsecurity/countrylonglats).
• Added new resource Cat2 Imsi(/vstp/cat2imsi).
• Added new resource Cat2 Gta(vstp/cat2gta).
• Added new resource Security Log Config(/vstp/securitylogconfig).
• Added new resource Accounting Measurement Options(/vstp/accountingmeasurementoptions).

Non-Backward Compatible Changes

• Changed Uri of CCMCCMappings (/commonsecurity/ccmccmappings).

Non-Interface Changes

• None

API Version v3.1 ( DSR Release 8.4.0.3.0_85.17.0 )

Backward Compatible Changes

• Supporting both Bulk Export and Bulk Import for Diameter, Fabr, Rbar, Vstp and Comagent.
• Added Bulk Export support for Connection Groups and Remote Servers MO.
• Initial Creation for area: commonsecurity.
• Added new resource Exceptions (/commonsecurity/neighboringcountries).
• Added Bulk Export support for all MO's.
• Added Bulk Export support for all MO's.
• Added Bulk Export support for all MO's.
• Added new resource NPP Service Rule Sets (/vstp/nppservicerulesets).
• Added new resource Common Screening Lists (/vstp/commonscreeninglists).
• Added new resource Mate Stps (/vstp/matestps).
• Added Bulk Export support for all MO's.
• Added new resource Mtp2 Options (/vstp/mtp2options).
• Added new resource Interface Mappings (/vstp/interfacemappings).
• Added new resource MTP2Board (/vstp/mtp2board).
• Added new resource NPP Action Sets (/vstp/nppactionsets).
• Added new resource PPS Options (/vstp/ppsoptions).
• Added new resource NPP Services (/vstp/nppservices).
• Added new resource IDPR Options (/vstp/idproptions.

Non-Backward Compatible Changes

• None

Non-Interface Changes

• None

API Version v3.0 ( DSR Release 8.4.0.0.0_84.15.0 )

Backward Compatible Changes

• Added new resource Users (admin/users).
• Added new resource Groups (admin/groups).
• Added new resource Sessions (admin/sessions).
• Added new resource Mp Profiles (diameter/mpprofiles).
• Added new resource Dynamic Peer Discovery-Realms(diameter/dpdrealms).
• Added new resource Dynamic Peer Discovery-DNS Sets(diameter/dpddnssets).
• Added new resource Dynamic Peer Discovery-Discovery Attributes(diameter/dpdattributesets).
• Added new resource Peer Node Alarm Groups (/diameter/peernodealarmgroups).
• Updated Peer Node Status (/diameter/peernodes/status). Added new attributes Peer Node Alarm Group Name and Alarm Ids.
• Updated Options (/diameter/options). Added new attribute Alarm Group Feature Enabled.
• Added new resource Connection Alarm Groups (/diameter/connectionalarmgroups).
• Updated Connection Status (/diameter/connections/status). Added new attributes Connection Alarm Group Name and Alarm Ids.
• Added new resource Topology Hiding Trusted Network Lists (diameter/trustednetworklists).
• Added new resource Path Topology Hiding Configuration Sets (diameter/pathtopologyhidingcfgsets).
• Added new resource S6a/S6d Hss Topology Hiding Configuration Sets (diameter/hsstopologyhidingcfgsets).
• Added new resource MME/SGSN Topology Hiding Configuration Sets (diameter/mmetopologyhidingcfgsets).
• Added new resource S9 PCRF Topology Hiding Configuration Sets (diameter/pcrftopologyhidingcfgsets).
• Added new resource AF/pCSCF Topology Hiding Configuration Sets (diameter/aftopologyhidingcfgsets).
• Added new resource Topology Hiding Protected Networks (diameter/protectednetworks).
• Added new resource View History (mon/alarmseventshistory).
• Added new resource View Trap Log (mon/alarmseventstraplog).
• Initial Creation for area: sbr.
• MMI support for Monitoring Location Area
• Updated Remote Signaling Points (/vstp/remotesignalingpoints). Added new optional attributes aliasPointCode1, aliasPointCode2, aliasPointCode1DomainType and aliasPointCode2DomainType.
• Updated M3RL Options (/vstp/m3rloptions). Added new optional attributes cnvAInat, cnvCgda, cnvCgdi, cnvCgdn, cnvCgdn24, cnvCgdn16, cnvClgItu, gtCnvDflt, itun16TcTimer and sparePCSupportEnabled.
• Updated Sccp Options (/vstp/sccpoptions). Added optional attribute itun16ScmgEnabled ( Itun16 Scmg Enabled).
• Updated GTA (/vstp/globaltitleaddresses). Added new optional attributes - gtmodName (GTT Modification Name), ccgt (Cancel called global title indicator), cgGtmod (Calling party GT modification indicator).
• Updated Link Sets (/vstp/linksets). Added new optional attribute enableCgGtmod.
• Updated GTT Actions (/vstp/gttactions). Added new optional attributes gtmodName (Global title modification identifier).
• Added new resource GTT Modification (/vstp/gttmods).
• Added new resource Home Entity (/vstp/homeentities).
• Added new resource MNP Options (/vstp/sccpmnpoptions).
• Added new resource SCCP Service Selectors (/vstp/sccpserviceselectors).
• Added new resource Sccp Applications (/vstp/sccpapplications).
• Added new resource Sccp Applications Status (/vstp/sccpapplicationstatus).
• Added new resource Sccp Applications Admin State(/vstp/sccpapplicationadminstate).
• Added new resource Default Conversions(/vstp/defaultconversions).
• Added new resource MTP Screening Rules(/vstp/mtpscreeningrules).
• Added new resource GTT Modification (/vstp/gttmods).
• Added new resource MTP Screen Sets (/vstp/mtpscreensets).
• Added new resource Sccp Loopsets (/vstp/sccploopsets).

Non-Backward Compatible Changes

• Updated Local Signaling Points with support for Multiple Point Code(TPC/SPC/CPC).

Non-Interface Changes

• None

API Version v2.1 ( DSR Release 8.3.0.0.0_83.15.0 )

Backward Compatible Changes

• Initial Creation for area: comagent.
• Added new resource Maintenance Application(diameter/applications).
• Added new resource Maintenance Signaling Firewall (diameter/signalingfirewalls).
• Added new resource Maintenance Peer DAMP Status (/diameter/peerdamps).
• Added new resource Maintenance Peer DAMP Connectivity Status (/diameter/peerdampconnectivity).
• Added new resource Maintenance DAMP Server Hostname Status (/diameter/dampserverhostnames).
• Added new resource Capacity Summary (/diameter/capacitysummary).
• Added new resource Peer Node Status (/diameter/peernodes/status).
• Added new resource Route Group Status (/diameter/routegroups/status).
• Added new resource Shared Traffic Throttle Group (/diameter/sharedtrafficthrottlegroups).
• Added new resource Connection Capactiy Dashboard (/diameter/connectioncapacitydashboard).
• Added new resource Route Lists Status (/diameter/routelists/status).
• Initial Creation for area: eir.
• Initial Creation for area: fabr.
• Initial Creation for area: scef.

Non-Backward Compatible Changes

• None

Non-Interface Changes

• None

API Version v2.0 ( DSR Release 8.2.0.0.0_82.15.0 )

Backward Compatible Changes

• Added new resource Mcc Mnc (diameter/mccmncs).
• Added new resource Mcc Mnc Mappings (/diameter/mccmncmappings).
• Added new resource Reserved Mcc Ranges (/diameter/reservedmccranges).
• Added new resource Common Application Options (/diameter/commonapplicationoptions).
• Initial Creation for area: rbar.
• Updated GTT Selectors (/vstp/gttselectors). Added new optional attributes - linksetName (Link Set Name), cdgttsn (CdPA GTT Set Name), cggttsn (CgPA GTT Set Name), cgssn (CgPA subsystem number), selid(Selector ID). Marked older attribute gttSetName from required to optional.
• Updated Link Sets (/vstp/linksets). Added new optional attribute gttmode.
• Updated SCCP Options (/vstp/sccpoptions). Added new optional attributes dfltfallback and dfltgttmode.
• Updated GTA (/vstp/globaltitleaddresses). Added new optional attributes - acn (Application Context Name), actsn (Action Set Name), cdselid (Called Party Selector Id), cdssn (Start Called Party SubSytem Number), cgpc (Calling Party Point Code), cgpcaction (Calling Party Point Code Actions), cgselid (Calling Party Selector Id), cgssn (Start Calling Party SubSytem Number), defmapvr (Default MAP Version), domain (Domain), ecdssn (End Called Party SubSytem Number), ecgssn (End Calling Party SubSytem Number), emapaddr (MAP based End Address), fallback (Fallback), family (Family), opc (Origin Point Code), opcode (OpCode), opcsn (Origin Point Code Set Name), optsn (Optional Set Name), pkgtype (Package Type), routingIndicator (Routing Indicator), smapaddr (MAP based Start Address).
• Updated GTT Sets (/vstp/gttsets). Added new optional attribute npsn (Not Present Set Name). Added new enum values - Cdssn, Cdgta, Cgpc, Cgssn, Imsi, Msisdn, Opc, Opcode - for attribute gttSetType.
• Added new resource GTT Action Sets (/vstp/gttactionsets).
• Added new resource GTT Actions (/vstp/gttactions).

Non-Backward Compatible Changes

• Maximum tuple (mapSetId + RSP + SSN) allowed for mapset and mrnset (mrnSetId + RSP) is reduced to 6000 and 3000 respectively.
• Allowed range value for mapSetId and mrnSetId is reduced to 6000 and 1500 respectively. This is applicable for /vstp/mapsets, /vstp/mrnsets, /vstp/gttaddresses and /vstp/gttactions.
• GTT Load sharing features - FGTTLS, IGTTLS and WGTTLS are enabled by default.

Non-Interface Changes

• None

API Version v1.1 ( DSR Release 8.1.0.0.0_81.20.0 )

Backward Compatible Changes

• Updated Software Versions (/admin/softwareversions). Added new attribute - hostname.
• Added new resource Application Priority Options (/diameter/applicationpriorityoptions).
• Updated Connection Configuration Sets (/diameter/connectionconfigurationsets). Added new optional attributes - cl1MinPriorityAllowed, cl2MinPriorityAllowed, cl3MinPriorityAllowed.
• Updated Pending Transaction Limit Configuration Sets (/diameter/pendingtransactionlimitingconfigurationsets). Added new optional attribute - pendConvergenceTime.
• Updated Egress Throttle Group Status (/diameter/egressthrottlegroupstatus). Added new optional attributes - averagePendTransHoldTime, egressRequestRate, numberOfPendingTransactions, offeredTrafficRate, percentTransDiverted, targetEtr.
• Updated Options (/diameter/options). Added new optional attributes - congestionDiscardPolicy, etgMode, ngnPs16PriorityAdminStateEnabled, ngnPsAnswerPriorityMode, ngnPsMaxPriority0Allowed, ngnPsMaxPriority1Allowed, ngnPsMaxPriority2Allowed.
• Updated Options (/diameter/options). Added new readonly attributes - ngnPsMaxNormalRequestPriority.
• Updated Options (/diameter/options). Extended the range - New range for ngnPsMinimumAnswerPriority is [P0,P3,P14,P15], New range for ngnPsMinimumInviolablePriority is [P3,P4,P15,P99].
• Updated Peer Route Rule (/diameter/peerrouterules). Extended the range - New range for msgPriority is [Nc,Pr0,Pr1,Pr2,Pr3,Pr4,Pr5,Pr6,Pr7,Pr8,Pr9,Pr10,Pr11,Pr12,Pr13,Pr14,Pr15].
• Updated Message Priority Configuration Sets (/diameter/messagepriorityconfigurationsets). Max value for priority is increased to 15.
• Added new optional attribute isTrafficMeasuringEnabled in Route Group (/diameter/routegroups).
• Added new optional attribute answerOnAnyEnabledConnection in Peer Node (/diameter/peernodes).
• Added new MP Profiles - Gen9V2_Relay, Gen9V2_Database, and Gen9V2_Session in MP Profile Assignment (/diameter/mpprofileassignments).
• Updated Message Priority Configuration Sets (/diameter/messagepriorityconfigurationsets). Max value for priority is increased to 15.
• Added new resource Signaling Ip Addresses (/diameter/signalingipaddresses).
• Updated Network Devices (/topo/networkdevices). Marked attributes as read only - persistentDhclient, hwAddr, ethtoolOpts, ethtoolAccelOpts.
• Initial Creation for area: vstp.

Non-Backward Compatible Changes

• None

Non-Interface Changes

• Updated descriptions against Onset and Abatement Threshold Levels in Pending Transaction Limiting Configuration Sets (/diameter/pendingtransactionlimitingconfigurationsets).
• Updated descriptions against Onset and Abatement Threshold Levels in Rate Limiting Configuration Sets (/diameter/ratelimitingconfigurationsets).

API Version v1.0 ( DSR Release 8.0.0.0.0_80.25.0 )

Backward Compatible Changes

• Initial Creation for area: admin.
• Initial Creation for area: all.
• Initial Creation for area: appworks.
• Initial Creation for area: auth.
• Initial Creation for area: bulk.
• Initial Creation for area: diameter.
• Initial Creation for area: mon.
• Initial Creation for area: topo.

Non-Backward Compatible Changes

• None

Non-Interface Changes

• None