7 About the SVC API Operations

This chapter describes information that you need to know to use the Oracle Communications Service Broker Social Voice Communicator (SVC) API.

About the SVC API

You use the SVC API to create, change, and delete subscriber accounts and data for SVC services. Like any RESTful API, the SVC API makes its services available to client applications through simple HTTP requests.

All API operations are accessible by your administrators, and a large majority are accessible by your subscribers to use for managing their accounts. Your subscribers typically access these API operations through a self-managed web portal that you set up for them. This may be a dedicated portal that you create for your subscribers, or may more typically involve integrating these operations into an existing customer-facing web application.

Your system administration staff will probably also use these portals to perform day-to-day provisioning and configuring tasks for SVC services. These API operations are also available to other services or programs that can access the web server.

The batch operation tools are also clients of this API. You use the batch operation tools to populate application data for SVC services in bulk.

About Exposing the API Operations to Your Subscribers

The specific API-based tasks that you allow your subscribers to access depends on your business requirements. For example you can expose operations that allow your subscribers to:

• Change their account details.

• Add or modify SVC Social Circle contacts and contact details.

• Add or modify SVC Social Voice contacts and contact details.

• Administer their own SVC Social Voicemail messages, including retrieving and deleting voice-mail messages, adding or changing their voice-mail greeting, or deactivating their voice-mail access.

About REST

The SVC API follows the style of a (REpresentational State Transfer) 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 resource can be a generic resource or an instance-specific resource. A generic resource is equivalent to a factory creation function in a traditional API. The client application would use the resource, for example, to create a new SVC subscriber SVC Social Voice contact. After the resource is created, it can be modified or inspected at its unique URI.

For example, to create objects that represent subscribers, the client application would send the following request to the API:

POST /svc/subscribers/subscriber_name

After the subscriber objects are created, the client application can inspect, modify, or delete the objects by sending a GET, PUT, or DELETE request to the address associated with that object instance. For a user with the user name of alice, for example, the URI to access the user's object would be:

/svc/subscribers/alice

The methods in the HTTP protocol used in the SVC 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.

Accessing the SVC API

In a Service Broker deployment, the SVC API is exposed by the managed server. Therefore, at least one managed server must be deployed and running in your environment.

Several types of clients connect to the managed server instance, including the Administration Console client process and JMX clients. The managed server listens for SVC API at the port configured for client HTTP access. Before using this API, ensure that the managed server is configured to accept web requests.

In a managed server cluster, all servers access the same data store. Therefore, it is not important which managed server the API client addresses.

Request URI Format

Clients access the services of the SVC RESTful API by sending HTTP requests to the managed server instance in the Service Broker managed domain. To use the API, the managed server must be configured and running.

The format of the URL to invoke operations in the API is:

https://host:port/svc/component/resourceId

The URL is made up of these parts:

• host:port: are the hostname and port of the managed server in the SVC domain. In the Domain Management, Servers page of the Administrator Console, these values correspond to the Host and Port values for a specific managed server instance. Note that the Port field value should be used as the port number, not the Admin Port or JMX-related port.

• component: is the data system component that you want to modify, create or query.

• resourceId: The identifier of the server instance on which the application operates.

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, SVC RESTful API operations are performed by using the POST and PUT 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. This example shows two name-value pairs user name for an object that represents a person. The data type of both parameters is string:

{adminUsername:"alice",password:"password"} 
 

JSON defines relatively few data types, including:

• number

• string

• boolean

• object

Certain parameters are composed of a value array. For example, you create a list of subscriber personal contacts using an array of name-value pairs:

[ { "mobile":"13811110000","default":true}, {"home":"01082311212"}, {"office":"[e-mail]"}]

to simple types, a parameter can be a complex type. An object type is a parameter that contains a nested set of subparameters. For example a policy rule contain all parameters required for the rule as shown in the following example:

[{
 "froms": [],
 "sequencialCall": true,
 "sequentialRingInterval": 30,
 "toAddresses": [
  "[e-mail]",
  "0118613611046326"
 ],
 "schedule": {
   "startDate":{
     "year":2009,
     "month":10,
     "day":24
   },
   "startTime":{
     "hour":1,
     "minute":00,
     "second":0
   },
   "endTime":{
     "hour":13,
     "minute":0,
     "second":0
   },
   "recurrentPeriod":1,
   "timezone":+8,
   "until":{
     "year":2010,
     "month":12,
     "day":24
   }
 },
 "priority":10
}]

In addition to validating the basic data type of a submitted parameter, SVC may validate the content of the parameter. For example, it may ensure that a number falls within an expected range or that dates meet the required format.

The values of certain parameters are limited to what are called word characters. Expressed in regular expression notation, the word character set is: [A-Za-z0-9_]. In other words, a value may contain upper or lower-case letters, numbers, and underscore characters.

Numeric values are expressed as digits. In some cases, a parameter may contain a range of numbers, such as the extension value for a PBX user. To specify a range of numbers, use the common numeric prefix for the number range followed by a wildcard, for example 898*. In this example, the range applies to all numbers that begin with the numbers 898, such as 89823 or 8981.

Data format requirements for each parameter, if applicable, are listed in "Provisioning and Managing Social Voice Communicator Services".

Creating and Updating Objects

To add subscribers and their contacts to SVC services, you use the SVC API to create the data objects that represent the entities you want to add.

The body of the POST request should contain the JSON-formatted data that describes the entity, such as the subscriber's name or contact numbers.

Each type of object can have mandatory parameters and optional parameters. A mandatary parameter must be included in the create object request with a value that meets the content requirements for that parameter.

When updating an object, you supply a new value for a modified setting in the body of a PUT request. In the body, you only need to supply the values for those parameters you want to modify, not for the entire object.

Too Many Subscribers Message

If a GET operation is required to return a set of more than 40,000 results, the operation fails and this message is returned:

Too many subscribers, please contact the admin to get subscribers data

In this case the return set is too large for a message to contain and you should have a database administrator retrieve this data from the database itself.

Errors and Exceptions

When an operation succeeds, the SVC API returns a response with HTTP status code 200.

There are a variety of reasons that an operation can fail. For instance, an object you are creating may reference an object that does not yet exist; the JSON body of a request may be malformed; or field data may not match the expected from.

In general however, if an error occurs, SVC returns a response that has an HTTP code reflecting the nature of the error. These error codes include:

• 400: The request body value is not correct. The response body contains detailed information about the error.

• 401: username or password is not correct.

• 403: the administrator does not have permission to access this object.

• 404: the URL style is unsupported or the resource does not exist in the system.

• 405: method is not allowed.

• 406: request method is not supported for this URL.

• 500: internal system error occurred.

• 503: service is unavailable.

SVC Data Types

The SVC API uses the following data types:

• The standard JSON data types listed in RFC 4627.

• Array of digit strings: A comma-separated list usually used to pass a list of MSISDN numbers.

• String: A Java J2SE standard string.

• Digit string: A string that can include of zero and positive integers 1-9.

• String (address): An RFC 2396 standard address.

• String (email): An RFC 822 standard email address.

• Null value: An empty pair of double quotes: “”

• UNIX timestamp: Milliseconds after January 1, 1970, 0:00:00 GMT.

API operation that transfer WAV files do so as attachments to HTTP requests.

Accessing the SVC API

The API is exposed by a Service Broker managed server. You cannot use the API to provision and manage SVC service before configuring at least one managed server in the Service Broker installation, and the managed server must be running.

The managed server listens for SVC API requests at the host address and port configured for the managed server. Specifically, the API is served on the port of the Port attribute, the Admin Port, or JMX-related ports for the server.

By default, security for the API is off. Turn on security to have basic authentication performed for the server.

Authentication and Authorization

By default, security is disabled for the SVC API. That is, clients can submit requests to the API without providing user credentials. While this may be suitable for test and evaluation systems, for production-level systems, access to the SVC RESTful API should be secured.

There are two types of SVC users:

• Administrators have full access to the functions of the API. These users can modify data objects associated with any SVC subscriber. Administrators are the only users allowed to perform these actions:

  • Create a subscriber account

  • Get a list of subscribers

  • Modify SVC Social Voicemail access

  • Delete SVC Social Voicemail access

  • Get a list of all accounts with SVC Social Voicemail access

• Subscribers can access the vast majority of the API operations, including adding or changing personal or SVC Social Voice contacts, and changing their voice-mail access.

SVC includes a default account administrator named admin. You set this user's default password during Service Broker installation. You can use this account to create additional administrator and subscriber accounts.

If security is enabled, client requests to the API must include the credentials of an administrator. The credentials should be supplied in the form of HTTP headers named name and password.

For example, a GET request submitted with user credentials would appear as follows:

GET /svc/subscriber HTTP/1.1
name: admin001
password: password
Host: 10.148.126.226
Accept: */*

A request that contains valid credentials but for a resource for which the user does not have privileges returns a 403 Forbidden error.

Note that the headers appear in HTTP requests in clear text. This may be acceptable in a test or evaluation system. However, in a production system, the connection should use Secure HTTP (HTTPS).

Batch Loader SVC Data Files

The following sections describe the data file format used by the batch loading tools to provision SVC accounts for each type of object used by the SVC services. For each data file, the sections show the name, schema, and sample data. You can find sample data files in these Batch Loader tools directories:

Oracle_home/admin_server/utils/bulkloader/onsdata
Oracle_home/admin_server/utils/bulkloader/vmdata

The first line in each sample data file shows the data type syntax and is not loaded by the Batch Loader or validation tools. This syntax line is optional in the file.

See "Social Voice Communicator API Reference" for detailed descriptions of the fields for each data type, and the corresponding parameter descriptions for the object creation operations.

All parameters are required unless indicated otherwise.

Table 7-1 lists the data files and their data types.

Table 7-1 Batch Load and Batch Check Data Types

Data Type	Used for	Can be Used for	Resource File in Oracle_home/ocsb61/utils/bukloader/onsdata
contact	Social Circle Contact	Batch loading	3.contact.csv
group	Personal Group (public or private)	Batch loading	5.group.csv
groupcontact	Private Group Contact	Batch loading	6.groupcontact.csv
onenumber	Social Circle One Number	Batch loading	4.onenumber.csv
policy	Social Voicemail Policy	Batch loading	7.policy.csv
publicgroupcontact	Public Group Contact	Batch loading	8.publicgroupcontact.csv
subscriber	Subscriber User	Batch loading and batch checking	2.subscriber.csv

Social Circle Contact

The contact data type represents an SVC Social Circle contact.

Data Type

contact

Data Format

Subscriber_Name,key,value,default

Example

alice,office,[e-mail],true

Notes

See the "Create a Social Circle One Number" operation for more information on the parameters.

Personal Group

The group data type represents SVC Social Voice public or private groups. The only difference between public and private data types is that public groups include a group_type.

Data Type

group

Data Format - Private Group

Subscriber_Name,Group_Name,Group_Number

Data Format - Public Group

Subscriber_Name,Group_Name,Group_Number,public

Example - Private Group

alice,family,456

Example - Public Group

alice,family,456,public

Notes

See "Create a Public Group" or "Delete a Private Group" for more information on the parameters.

Private Group Contact

The groupcontact data type represents subscriber's SVC Social Voice private group contacts.

Data Type

groupcontact

Data Format

Subscriber_Name,Group_Name,Contact_Name,number,isActive

Example

alice,family,carol,[e-mail],true

Notes

See "Create Personal Contacts in a Subscriber Account" for more information on the parameters.

Social Circle One Number

The onenumber data type represents SVC Social Circle one numbers.

Data Type

onenumber

Data Format

Subscriber_Name,One_Number,type

Example

"alice","123","personal"

Notes

See "Create a Social Circle One Number" for more information on the parameters.

Social Voicemail Policy

The policy data type represents SVC Social Voicemail policies. You send or retrieve policies as parameters when performing these operations:

• Create a Policy Rule for a Social Circle Contact

• Get a Social Circle Policy Rule Details

• Modify a Social Circle Policy Rule

• Delete a Social Circle Policy Rule

• Get All Social Circle One Number Contacts for a Subscriber

• Get Details for a Social Circle Contact

Data Type

list

Data Format

Subscriber_Name,One_Number,Policy_Name,froms,sequentialCall,sequentialRingInterval, toAddress,priority,schedule

Example

alice,123,policy1,address[[e-mail];group|family,true,,[e-mail]@oracle.com,1,2009|11|24;9|30|0;2012|12|24|;18|0|0;2;-8

Notes

See "Create a Policy Rule for a Social Circle Contact" for more information on the parameters.

Public Group Contact

The publicgroupcontact data type represents subscriber's SVC Social Voice public group contacts.

Data Type

publicgroupcontact

Data Format

Owner_Name,Group_Name,Contact_Name,number,isActive,public

Example

alice,family,carol,[e-mail],true,public

Notes

See "Create Personal Contacts in a Subscriber Account" for more information on the parameters.

Subscriber User

This subscriber data type represents SVC subscriber administrator accounts.

Note:

Administrator accounts cannot be created with the Batch Loader.

Data Type

subscriber

Data Format

username,password,isPONPresented

Example

bob,12345,TRUE

Notes

See the "Create Subscriber Accounts" operation for parameter details.

Voice-Mail Service

Represents SVC Social Voicemail access.

Data Type

vmbox

Data Format

Subscriber_Name,One_Number

Example

alice,123

Notes

See "Activate Social Voicemail for Subscribers" for more information on the parameters.