| Oracle® Communications Service Broker SVC Implementation Guide Release 6.0 Part Number E24885-02 |
|
|
View PDF |
| Oracle® Communications Service Broker SVC Implementation Guide Release 6.0 Part Number E24885-02 |
|
|
View PDF |
This chapter describes information that you need to know before using the Oracle Communications Service Broker SVC API.
The SVC API is the interface for creating, changing, and deleting SVC 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.
The specific API-based tasks that you allow your subscribers to access (usually through an SVC self-management portal) 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.
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.
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.
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.
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":"alice@oracle.com"}]
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": [
"tom@oracle.com",
"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".
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.
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.
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.
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.
The API is exposed by a Service Broker Managed Server. You cannot use the API to provision and manage SVC service prior to 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.
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).
The following sections describe the data file format used by the batch loading tools to provision SVC account, 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_console/utils/bulkloader/onsdata Oracle_home/admin_console/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 | Can be Used for | Resource File |
|---|---|---|
|
contact |
Batch loading |
contact.csv |
|
group |
Batch loading |
group.csv |
|
groupcontact |
Batch loading |
groupcontact.csv |
|
onenumber |
Batch loading |
onenumber.csv |
|
policy |
Batch loading |
policy.csv |
|
subscriber |
Batch loading and batch checking |
subscriber.csv |
This data type represents SVC subscriber administrator accounts.
Note:
Administrator accounts cannot be created with the Batch Loader.subscriber
User_Name,password,isPONPresented
bob,12345,TRUE
See "Create Subscriber Accounts" for parameter details.
Represents SVC Social Circle One-numbers.
onenumber
Subscriber_Name,One_Number,type
"alice","123","personal"
See "Create a Social Circle One-number" for more information on the parameters.
Represents an SVC Social Circle contact.
contact
Subscriber_Name,key,value,default
alice,office,alliceoffice@oracle.com,true
See "Create a Social Circle One-number" for more information on the parameters.
Represents SVC Social Voice groups.
group
Subscriber_Name,Group_Name,Group_Number
alice,family,456
See "Create a Social Voice Group" for more information on the parameters.
Represents subscriber's SVC Social Voice contacts.
groupcontact
Subscriber_Name,Group_Name,Contact_Name,number,isActive
alice,family,carol,carol@oracle.com,true
See "Create Personal Contacts in a Subscriber Account" for more information on the parameters.
Represents SVC Social Voicemail policies. You send or retrieve policies as parameters when performing these operations:
list
Subscriber_Name,One_Number,Policy_Name,from,sequentialCall,sequentialRingInterval, toAddress,priority,schedule
alice,123,policy1,address[23456@asfddd.com;group|family,true,,aliceoffice@oracle.comalicehome@oracle.com,1,2009|11|24;9|30|0;2012|12|24|;18|0|0;2;-8
See "Create a Policy Rule for a Social Circle Contact" for more information on the parameters.
Represents SVC Social Voicemail access.
vmbox
Subscriber_Name,One_Number
alice,123
See "Activate Social Voicemail for Subscribers" for more information on the parameters.
Represents SVC Social Voicemail access policies.
vmboxprop
Subscriber_Name,One_Number,EnableVoiceMail,password,voiceMessageExpireDays,maximumPhoneMessageDuration,maximumInboundMessagesInMailBox,maximumOutboundMessagesInMailBox,notifyEmailAddress
alice,123,true,password,30,100,10,10,alice@oracle.com
See "Get Social Voicemail Settings" for more information on the parameters.
|
 Copyright © 2011, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|