The Sentinel REM extension provides a RESTful HTTP provisioning API.

Tip To use the Sentinel Provisioning REST Web Interface and Machine API, you will need to configure a Rhino instance using the Rhino Element Manager (REM).
Tip The Sentinel SDK contains a Python script called sentinel-rest-example in the build/bin directory. It implements the examples discussed here and a few more. View the script source for requirements and usage instructions.

This page covers

Accessing the Provisioning REST API

To access the Provisioning REST API:

1

Ensure the Sentinel REM extension is installed in REM.

2

Start REM.

3

Access the Sentinel Provisioning API at [http://localhost:8080/rem/sentinel/api] (replace localhost with some other hostname if REM is not being run locally).
Tip Access is restricted to users configured through REM using HTTP BASIC authorization. If you’re using a web browser, it will prompt you to enter a username and password the first time you access any part of the API.

Listing and browsing resources

You can list and browse resources through the Sentinel Provisioning API.

Listing resources

You can find a listing of all available resources at the top-level URL for the API (for example, [http://localhost:8080/rem/sentinel/api]).

The list can be in either:

  • HTML format (for viewing in a browser)

  • an APP Service Document (application/atomsvc+xml), that can be parsed by a scripted client.

Browsing resources

From the top-level API URL, you can browse into the available resources. Each resource in turn lists its own sub-resources. All of the sub-resources require a rhinoInstanceId query parameter. This should exactly match the name of a Rhino instance configured in REM (such as rhinoInstanceId=Local). Most of the sub-resources also require a selectionKey query parameter in the form of platformOperator:networkOperator:sessionType:planId:subscriptionId - such as selectionKey=OpenCloud::::

Example 1:

http://localhost:8080/rem/sentinel/api/featureexecutionscripts returns a sub-resource listing for feature execution scripts:

<feature>
  <name>FeatureExecutionScripts</name>
  <resources>
    <link title="Feature Execution Scripts" href="http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts" rel="entries"/>
    <link title="Feature Execution Script Execution Point Associations" href="http://localhost:8080/rem/sentinel/api/featureexecutionscripts/executionpoints" rel="associations"/>
  </resources>
</feature>

Example 2:

Following the entries relation to the scripts resource, by adding the rhinoInstanceId and selectionKey parameters, http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts?rhinoInstanceId=Local&selectionKey=OpenCloud

returns a paged listing of feature execution scripts configured in your local Rhino instance for platform operator OpenCloud:

<featureExecutionScripts next="http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts?rhinoInstanceId=Local&selectionKey=OpenCloud::::&page=2">
  <featureExecutionScript>
    <name>default_DiameterAccess_NetworkPreCreditCheck</name>
    <resources>
      <link title="default_DiameterAccess_NetworkPreCreditCheck" href="http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts/default_DiameterAccess_NetworkPreCreditCheck?rhinoInstanceId=Local&selectionKey=OpenCloud::::" rel="config"/>
    </resources>
  </featureExecutionScript>
  ...
  <featureExecutionScript>
    <name>default_Mediation_CreditAllocatedPostOcsCC</name>
    <resources>
      <link title="default_Mediation_CreditAllocatedPostOcsCC" href="http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts/default_Mediation_CreditAllocatedPostOcsCC?rhinoInstanceId=Local&selectionKey=OpenCloud::::" rel="config"/>
    </resources>
  </featureExecutionScript>
</featureExecutionScripts>

  • The next and prev attributes contain the URLs for the next and previous pages of results.

  • The link entries contain the URLs for accessing the individual feature execution script resource entities.

Specifying content type

By default, the API accepts and returns application/xml, but also supports application/json. To request content in JSON format, simple set the http Accept request header to application/json.

For example:

{{wget --header='Accept: application/json' ...}}
for {{.../featureexecutionscripts/scripts/default_DirectAccess_SessionStart?rhinoInstanceId=Local&selectionKey=OpenCloud::::}}

returns a JSON object representing the requested feature execution script.

{"featureExecutionScript": {
  "name": "default_DirectAccess_SessionStart",
  "src": "featurescript OnSessionStart { if not currentNextStep.refuseDialog and not currentNextStep.relayDialog { run AcceptCamelVoiceV1V2V3 } }"
}}

Provisioning using simple tools and scripts

Higher-level clients can be used to interact with the REST API from Java or other application code, but you really just need to be able to make HTTP requests. See these examples:

Adding a feature execution script with curl (XML)

Request

 
curl -H 'Accept: application/xml' \
     -H 'Content-Type: application/xml' \
     -i -w '\nHTTP STATUS: %{http_code}\nTIME: %{time_total}\n' \
     -X POST \
     -u "username:password" \
     -d "<featureExecutionScript><name>my_new_feature_script</name><src>featurescript newScript { }</src></featureExecutionScript>" \
     "http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts?rhinoInstanceId=Local&selectionKey=OpenCloud::::"

Response

 
HTTP/1.1 201 Created
Date: Tue, 13 Sep 2011 20:42:15 GMT
Location: http://localhost:8080/rem/sentinel/api/featureexecutionscripts/scripts/my_new_feature_script?rhinoInstanceId=Local&selectionKey=OpenCloud::::
Content-Length: 0
Server: Jetty(6.1.24)

Adding a subscriber with curl (JSON)

Request

 
curl -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -i -w '\nHTTP STATUS: %{http_code}\nTIME: %{time_total}\n' \
     -X POST \
     -u "username:password" \
     -d '{ "name": "34600000002", "subscriberData": [ {"name": "FriendsAndFamilyEnabled", "type": "Boolean", "valueBoolean": "true"}, {"name": "FriendsAndFamilyList", "type": "StringArray", "valueArray": ["34600000001"] } ] }' \
     "http://localhost:8080/rem/sentinel/api/subscriberdata/records?rhinoInstanceId=Local&selectionKey=OpenCloud::::"

Response

 
HTTP/1.1 201 Created
Date: Tue, 13 Sep 2011 21:07:03 GMT
Location: http://localhost:8080/rem/sentinel/api/subscriberdata/records/34600000002?rhinoInstanceId=Local&selectionKey=OpenCloud::::
Content-Length: 0
Server: Jetty(6.1.24)

Turning on HomeZone for a subscriber using Ruby (JSON)

require 'rubygems'
require 'json'
require 'net/http'

Net::HTTP.start('localhost', '8080') {|http|
  req = Net::HTTP::Get.new('/rem/sentinel/api/subscriberdata/records/34600000003?rhinoInstanceId=Local&selectionKey=OpenCloud::::', {'Accept' => 'application/json'})
  req.basic_auth 'username', 'password'
  response = http.request(req)
  subscriber = JSON.parse(response.body)
  subscriber['subscriberData'].each {|item|
    if item['name'] == 'HomeZoneEnabled'
      item['valueBoolean'] = true;
    end
  }

  req = Net::HTTP::Put.new('/rem/sentinel/api/subscriberdata/records/34600000003?rhinoInstanceId=Local&selectionKey=OpenCloud::::', {'Content-Type' => 'application/json'})
  req.basic_auth 'username', 'password'
  response = http.request(req, JSON.generate(subscriber))
}

Result codes and error responses

The Provisioning REST API returns the following Result codes and Error responses

Result codes

The API returns these codes

Result code

Description

200 OK

The request to list or retrieve a record was successful

201 Created

The record posted was successfully created

204 No Content

The update or delete operation was successful

400 Bad Request

Incorrectly configured request. Check the response body for specific error information

401 Unauthorized

The request was not authorized. Check that the username and password are correct in the request

404 Not Found

The requested resource could not be found. Check the response body for specific error information

406 Not Acceptable

The requested media type is not supported

500 Internal Server Error

An internal error occurred while processing the request. Check the response body for specific error information

Error responses

You can find more information for result codes 400, 404, and 500 in an error response entity in the response body, in the requested content type (XML or JSON). For example:

XML

<error>
    <type>...</type>
    <message>...</message>
</error>

JSON

{
    "type": "...",
    "message": "..."
}

Here are the possible responses:

Error type

Associated Result Code

Description

CollectionNotFound

404 Not Found

The collection/table/scope containing the requested entity could not be found

EntityNotFound

404 Not Found

The requested entity could not be found

EntityMissing

400 Bad Request

Post request did not contain an entity in the request body

EntityAlreadyExists

400 Bad Request

Post request attempted to create an entity that already exists

RequiredParameterMissing

400 Bad Request

A required query parameter was not provided

ParameterInvalid

400 Bad Request

One of the query parameters provided was invalid

RequestInconsistent

400 Bad Request

Put request attempted to update an entity with an id/name in the request body that didn’t match the id/name in the URL

ServerError

500 Internal Server Error

An internal error occurred while processing the request

PageNotFound

404 Not Found

The requested page of the paged resource listing could not be found

NotAcceptable

406 Not Acceptable

Requested media type is not supported (XML-only response, since media type could not be determined)
Next page