16 Using the Location Service RESTful Interface

This chapter describes the Oracle Communications Converged Application Server RESTful API, a RESTful interface that creates, modifies, and deletes address-of-record (AOR) entries in the Location Service.

About the Location Service RESTful Interface

This chapter lists RESTful operations for the Location Service, including the parameters accepted and returned by each operation and examples of HTTP requests and responses.

These operations store, lookup, and clear address-of-record registrations in the Location Service. An AOR is a SIP or SIPS URI that points to a domain with a location service that can map the URI to another URI where the user might be available. Typically, the location service is populated through registrations. An AOR is frequently thought of as the “public address” of the user.

For example, to create objects that represent the AOR, the client application sends the following request to the API:

POST / context-root/locationservice/registration/sip:alice@example.com

About REST

The Location Service API follows the style of a REpresentational State Transfer (REST) interface.

In a RESTful API, functions are distinguished by the combination of a particular URI and the HTTP method used to access it. In general, the URI identifies the resource on which to act, and the HTTP method identifies the type of action to perform.

The methods in the HTTP protocol used in the Location Service RESTful API - POST, GET, PUT, and DELETE - correspond to the programming operations commonly known as CRUD operations. CRUD, which stands for create, read, update, and delete, represent the common operations applicable in data-oriented APIs. The equivalent function calls in a traditional API may be similar to createUser(), getUser(), setUser(), and deleteUser(). In this case, the instance on which the function operates is typically identified through an input parameter.

About JSON Body Parameters

Operations that are performed by using the GET or DELETE HTTP methods do not require input values other than what is provided in the URL and headers of the client request. That is, they do not require HTTP body content to be supplied in the invocation request.

However, Location Service RESTful API operations are performed by using the POST methods require additional input data. The API takes input parameters in the form of JSON (JavaScript Object Notation) data in the body of the request.

JSON is a data exchange format based on JavaScript that is commonly used to pass information between web clients and servers over HTTP. In the body of the request, JSON data appears as one or more name-value pairs.

About the Context Root

The context root is set when the application is deployed. By default Converged Application Server uses proxyregistrarssr as context root. You can change the context root by editing the application.xml in the file

MW_home/occas_5.1/applications/proxyregistrarear-5.1.0.0.0.ear.

To learn more, see the chapter on configuring the Proxy Registrar in Converged Application Server Administrator's Guide.

Using Authentication and Authorization

The Location Service RESTful interface's security consists of authentication and authorization. Authentication supports HTTP Digest and X-3GPP-Asserted-Identity header. Authorization allows only the AOR owner to access and update their registration information.

To use HTTP Digest and X-3GPP-Asserted-Identity authentication you must configure Converged Application Server to handle these header types for authentication. To learn more, see the chapters on configuring Digest authentication and 3GPP HTTP authentication assertion providers in Converged Application Server Security Guide.

RESTful APIs for the Location Service

The RESTful Location Service APIs are:

Store Registrations for Address-of-Record
Lookup an Address-of-Record
Clear All Address of Record Bindings

Store Registrations for Address-of-Record

Stores registrations for the AOR.

An HTTP response 200 message is returned on success.

HTTP Method

POST

URI

proxyregistrarssr/locationservice/registration/uri

Where the URI is of the form: sip:username@domain.com

Request Header

Accept application/json, Content-Type application/json

Request Body

The cseq, contactAddress, and callId parameters are required and case-sensitive.

[
{
"cseq":7,
"callId":"a97d0d177949304c@enpoYWkwMS5hcGFjLmJlYS5jb20.",
"contactAddress":"<sip:alice@10.182.101.231:5060>;expires=3600",
"methodsParam":"INVITE,BYE,CANCEL,ACK"
}
]

Response Body

[{
"aor":"sip:alice@example.com",
"contactUri":"sip:alice@10.182.101.231:5060",
"contactAddress":"<sip:alice@10.182.101.231:5060>;expires=3600",
"callId":"a97d0d177949304c@enpoYWkwMS5hcGFjLmJlYS5jb20.",
"cseq":7,
"qvalue":1.0,
"methodsParam":"INVITE,BYE,CANCEL,ACK",
"expiresParam":3600,
"expires":1335173253469,
"path":null,
"sipInstanceId":null,
"regId":null,
"remoteIP":"localhost",
"remotePort":2169,
"created":1335169653469,
"updated":1335169653469
}]

Example

Example 16-1 stores an AOR registration in the Proxy Registrar using the following parameters:

final String DEST_URL = 
"/proxyregistrarssr/locationservice/registration/sip:alice@example.com"; 
private String account_name = "alice";
private String account_pass = "welcome1";

Example 16-1 Storing AOR Registrations

public void StoreRegistration() throws Exception {
String restUrl = "http://127.0.0.1:7001" + DEST_URL;
URL url = new URL(restUrl);
HttpURLConnection httpConn = (HttpURLConnection)url.openConnection();
setHttpConnReqProperty(httpConn);
httpConn.setRequestMethod("POST");
httpConn.connect();
OutputStreamWriter outWriter = new OutputStreamWriter(httpConn.getOutputStream(), "UTF-8");
String requestRegistration = "[{\"cseq\":2," +
"\"callId\":\"LSRestfulTest.testStoreRegistration@10.182.107.197:5071\"," +
"\"contactAddress\":\"<sip:alice@10.182.107.197:5071>;expires=300\"," +
"\"methodsParam\":\"INVITE,BYE,CANCEL,ACK\"}]";
outWriter.write(requestRegistration);
outWriter.flush();
outWriter.close();
int responseCode = httpConn.getResponseCode();
assertEquals(HttpURLConnection.HTTP_UNAUTHORIZED, responseCode);
String digestValue = httpConn.getHeaderField(HttpAuthenticationUtils.HEADER_WWW_AUTHENTICATE);
// Calculate the authorization header value from the authenticate header
String authorizeValue = caculateAuthorizationFromDigest(digestValue, DEST_URL, account_name, 
account_pass, "POST");
httpConn = (HttpURLConnection)url.openConnection();
setHttpConnReqProperty(httpConn);
httpConn.setRequestMethod("POST");
httpConn.setRequestProperty(HttpAuthenticationUtils.HEADER_AUTHORIZATION, authorizeValue);
httpConn.connect();
outWriter = new OutputStreamWriter(httpConn.getOutputStream(), "UTF-8");
outWriter.write(requestRegistration);
outWriter.flush();
outWriter.close();
responseCode = httpConn.getResponseCode();   
assertEquals(HttpURLConnection.HTTP_OK, responseCode);
InputStream input = httpConn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(input, "UTF-8"));
String responseContent = "";
String line = null;
while ((line = reader.readLine()) != null) {
responseContent += line;
}
      reader.close();     
      
httpConn.disconnect();
  }
  void setHttpConnReqProperty(HttpURLConnection httpConn) throws ProtocolException {
    httpConn.setRequestProperty("Accept", "application/json");
    httpConn.setRequestProperty("Content-Type", "application/json");   
    httpConn.setDoInput(true);
    httpConn.setDoOutput(true);
  }

Lookup an Address-of-Record

This API looks up all bindings of an AOR. An HTTP response 200 message is returned on success.

HTTP Method

GET

URI

proxyregistrarssr/locationservice/registration/uri

Request Header

Accept application/json, Content-Type application/json

Request Body

None.

Response Body

[{
"aor":"sip:alice@example.com",
"contactUri":"sip:alice@10.182.101.231:5060",
"contactAddress":"<sip:alice@10.182.101.231:5060>;expires=3600",
"callId":"a97d0d177949304c@enpoYWkwMS5hcGFjLmJlYS5jb20.",
"cseq":7,
"qvalue":1.0,
"methodsParam":"INVITE,BYE,CANCEL,ACK",
"expiresParam":3600,
"expires":1335173253469,
"path":null,
"sipInstanceId":null,
"regId":null,
"remoteIP":"localhost",
"remotePort":2169,
"created":1335169653469,
"updated":1335169653469
}]

Example

Example 16-2 stores an AOR registration in the Proxy Registrar using the following parameters:

final String DEST_URL = 
"/proxyregistrarssr/locationservice/registration/sip:alice@example.com"; 
private String account_name = "alice";
private String account_pass = "welcome1";

Example 16-2 Looking Up An AOR

public void LookupRegistration() throws Exception {
String restUrl = "http://127.0.0.1:7001" + DEST_URL;
URL url = new URL(restUrl);
HttpURLConnection httpConn = (HttpURLConnection)url.openConnection();
setHttpConnReqProperty(httpConn);
httpConn.setRequestMethod("GET");
httpConn.connect();
String digestValue = httpConn.getHeaderField(HttpAuthenticationUtils.HEADER_WWW_
AUTHENTICATE);  
String authorizeValue = caculateAuthorizationFromDigest(digestValue, DEST_URL, account_name, account_pass, "GET");
httpConn = (HttpURLConnection)url.openConnection();
setHttpConnReqProperty(httpConn);
httpConn.setRequestMethod("GET");
httpConn.setRequestProperty(HttpAuthenticationUtils.HEADER_AUTHORIZATION, authorizeValue);   
httpConn.connect();
responseCode = httpConn.getResponseCode();
assertEquals(HttpURLConnection.HTTP_OK, responseCode);
InputStream input = httpConn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(input, "UTF-8"));
String responseContent = "";
String line = null;
while ((line = reader.readLine()) != null) {
responseContent += line;
}
reader.close();
httpConn.disconnect();   
 
  }

Clear All Address of Record Bindings

An HTTP response 204 message is returned on success.

HTTP Method

DELETE

URI

proxyregistrarssr/locationservice/registration/uri

Where the URI is of the form: sip:username@domain.com

Parameters

None.

Request Header

None.

Request Body

None.

Response Body

None.

Examples

Example 16-3 clears an AOR registration in the Proxy Registrar using the following parameters:

final String DEST_URL = 
"/proxyregistrarssr/locationservice/registration/sip:alice@example.com"; 
private String account_name = "alice";private String account_pass = "welcome1";

Example 16-3 Clearing AOR Binding

public void testClearAllBindings() throws Exception {
String restUrl = "http://127.0.0.1:7001" + DEST_URL;
URL url = new URL(restUrl);
HttpURLConnection httpConn = (HttpURLConnection)url.openConnection();
setHttpConnReqProperty(httpConn);
httpConn.setRequestMethod("DELETE");   
httpConn.connect();
String digestValue = httpConn.getHeaderField(HttpAuthenticationUtils.HEADER_
WWW_AUTHENTICATE);
String authorizeValue = caculateAuthorizationFromDigest(digestValue, DEST_URL, account_name, account_pass, "DELETE");
httpConn = (HttpURLConnection)url.openConnection();
setHttpConnReqProperty(httpConn);
httpConn.setRequestMethod("DELETE");
 
httpConn.setRequestProperty(HttpAuthenticationUtils.HEADER_AUTHORIZATION, authorizeValue);
httpConn.connect();
respCode = httpConn.getResponseCode();   
assertEquals(HttpURLConnection.HTTP_NO_CONTENT, respCode);   
httpConn.disconnect();   

 }