Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide Release 5.1 E37533-01 |
|
|
PDF · Mobi · ePub |
This chapter describes the use of the Application Subscription Management RESTful interface in Oracle Communications Services Gatekeeper.
Services Gatekeeper supports Open Mobile Alliance (OMA) General Service Subscription Management (GSSM) functionality including subscription management, subscription profile access and subscription validation with Application Subscription Management.
For information on the OMA GSSM specification see:
http://technical.openmobilealliance.org/Technical/release_program/gssm_v1_0.aspx
Application Subscription Management includes both a communication service and a RESTful interface for managing and querying service subscription status. Applications use the RESTful interface to manage subscriptions and query subscription status. Application Subscription Management grants or restricts application access to a subscriber's communication service(s) depending on the subscription status. Application Subscription Management also supports OAuth authentication when required.
For information on using the Application Subscription Management communication service, including deploying, configuring and monitoring, see the chapter Application Subscription Management in Oracle Communications Services Gatekeeper Communication Service Guide.
When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of these operations can be found at
http://
host:port/subscription/application.wadl
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The Subscribe operation creates a new application service subscription request for a subscriber based on MSISDN.
http://host:port/subscription
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The request body for Subscribe accepts the following parameters:
applicationName. String. The name of the application subscribed to.
subscriberAddress. String. The MSISDN of the subscriber making the request.
The response header indicates successful creation of the subscription request. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See the chapter on Application Subscription Management in Oracle Communications Services Gatekeeper Communication Service Guide, for more information on error messages.
The response body contains the following parameters:
subscriptionResponse. String. The Services Gatekeeper generated response containing the subscription ID.
subscriptionID. String. The ID of the new subscription.
Example 5-1 shows a sample Subscribe request.
Example 5-1 Subscribe Request Example
GET /subscription/query/queryBySubscriptionId/e4e3cb51-994b-46e1-b0d1-0757a8bca25f HTTP/1.1Host: example.com:80Accept: application/json
Example 5-2 shows a sample Subscribe response.
The Unsubscribe operation is used to request a subscription deletion.
http://host:port/subscription
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The Unsubscribe request header contains the subscription ID to be deleted. The MIME-type for the Content-Type header field is application/json.
The response header indicates successful change of the ACR status. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See the chapter on Application Subscription Management in Oracle Communications Services Gatekeeper Communication Service Guide, for more information on error messages.
Example 5-3 shows a sample Unsubscribe request.
Example 5-3 Unsubscribe Request Example
DELETE /subscription/e4e3cb51-994b-46e1-b0d1-0757a8bca25f HTTP/1.1 Host: example.com:80 Accept: application/json
Example 5-4 shows a sample Unsubscribe response.
The Suspend operation suspends an existing service subscription for a subscriber based on subscription ID.
http://host:port/subscription/suspend/subscriptionID
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
subscriptionID is the ID of the subscription to be suspended.
The Suspend request header contains the subscription ID to be suspended. The MIME-type for the Content-Type header field is application/json
The response header indicates successful subscription suspension. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See the chapter on Application Subscription Management in Oracle Communications Services Gatekeeper Communication Service Guide, for more information on error messages.
Example 5-5 shows a sample Suspend request.
Example 5-5 Suspend Request Example
PUT /subscription/suspend/e4e3cb51-994b-46e1-b0d1-0757a8bca25f HTTP/1.1Host: example.com:80Accept: application/json
Example 5-6 shows a sample Suspend response.
The Unsuspend operation unsuspends an existing service subscription for a subscriber based on subscription ID.
http://host:port/subscription/unsuspend/subscriptionID
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
subscriptionID is the ID of the subscription to be suspended.
The Unsuspend request header contains the subscription ID to be unsuspended. The MIME-type for the Content-Type header field is application/json
The response header indicates successful subscription unsuspension. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See the chapter on Application Subscription Management in Oracle Communications Services Gatekeeper Communication Service Guide, for more information on error messages.
Example 5-7 shows a sample Unsuspend request.
Example 5-7 Unsuspend Request Example
PUT /subscription/unsuspend/e4e3cb51-994b-46e1-b0d1-0757a8bca25f HTTP/1.1Host: example.com:80Accept: application/json
Example 5-8 shows a sample Unuspend response.
The Notify operation notifies a registered application of a subscription management request.
http://host:port/notify
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The request body for Notify accepts the following parameters:
subscriptionNotification. The Services Gatekeeper generated notification containing the following parameters:
subscriptionID. String. The ID of the subscription request.
applicationName. String. The name of the application receiving the request.
subscriberAddress. String. The MSISDN of the requesting subscriber.
operation. String. The subscription request type. For example, Subscribe or Unsubscribe.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See the chapter on Application Subscription Management in Oracle Communications Services Gatekeeper Communication Service Guide, for more information on error messages.
Example 5-9 shows a sample Notify request.
Example 5-9 Notify Request Example
POST /notifysubscription HTTP/1.1Host: example.com:80Accept: application/jsonContent-Type: application/jsonContent-Length: 173{"subscriptionNotification":{"subscriptionId":"e4e3cb51-994b-46e1-b0d1-0757a8bca25f","applicationName":"Oracle News","subscriberAddress":"tel:1111","operation":"Subscribe"}}
Example 5-10 shows a sample Notify response.
The Confirm operation is used by applications to confirm subscription requests.
http://host:port/subscription/confirm
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The request body for Confirm accepts the following parameters:
operation. String. The subscription request operation being confirmed. For example, Subscribe or Unsubscribe.
confirmResult. String. The subscription request status. For example, approved.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See the chapter on Application Subscription Management in Oracle Communications Services Gatekeeper Communication Service Guide, for more information on error messages.
The response body contains the following parameter:
oauthAccessToken. String. If OAuth is required, Services Gatekeeper returns an OAuth accessToken in the response.
Example 5-11 shows a sample Confirm request.
Example 5-11 Confirm Request Example
PUT /subscription/confirm/e4e3cb51-994b-46e1-b0d1-0757a8bca25f HTTP/1.1Host: example.com:80Accept: application/jsonContent-Type: application/x-www-form-urlencodedContent-Length: 42operation=Subscribe&confirmResult=Approved
Example 5-12 shows a sample Confirm response with an OAuth accessToken.
The queryBySubscriberAddress operation retrieves a user's subscription information based on the subscriber address.
http://host:port/subscription/query/queryBySubscriberAddress
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The queryBySubscriberAddress request header contains the subscriber address (MSISDN) to be queried. The MIME-type for the Content-Type header field is application/json.
The response header includes the request status. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See the chapter on Application Subscription Management in Oracle Communications Services Gatekeeper Communication Service Guide, for more information on error messages.
The request body for queryBySubscriberAddress contains the following parameters:
subscriptionList. The Services Gatekeeper generated list containing the following parameters:
subscriptionInfo. Array. Contains the following parameters for each subscription.
applicationName. String. The name of the subscribed application.
subscriberAddress. String. The MSISDN of the subscriber.
status. String. The subscription status. For example, Pending.
Example 5-13 shows a sample queryBySubscriberAddress request.
Example 5-13 queryBySubscriberAddress Request Example
GET /subscription/query/queryBySubscriberAddress/tel:1111?offSet=0&batchSize=2 HTTP/1.1 Host: example.com:80 Accept: application/json
Example 5-14 shows a sample queryBySubscriberAddress response.
Example 5-14 queryBySubscriberAddress Response Example
HTTP/1.1 200 OK Content-Type: application/json Date: Wed, 07 Nov 2012 06:56:05 GMT {"subscriptionList":{"subscriptionInfo":[{"applicationName":"Oracle Jokes","subscriberAddress":"tel:1111","status":"SubscribePending"},{"applicationName":"Oracle News","subscriberAddress":"tel:1111","status":"UnSubscribePending"}]}}
The queryByApplicationName operation retrieves a list of subscribers to an application based on the application ID.
http://host:port/subscription/query/queryByApplicationName
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The queryByApplicationName request header contains the application name to be queried. The MIME-type for the Content-Type header field is application/json.
The response header includes the request status. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See the chapter on Application Subscription Management in Oracle Communications Services Gatekeeper Communication Service Guide, for more information on error messages.
The request body for queryByApplicationName contains the following parameters:
subscriptionList. The Services Gatekeeper generated list containing the following parameters:
subscriptionInfo. Array. Contains the following parameters for each subscribed user.
applicationName. String. The name of the subscribed application.
subscriberAddress. String. The MSISDN of the subscriber.
status. String. The subscription status. For example, Pending.
Example 5-15 shows a sample queryByApplicationName request.
Example 5-15 queryByApplicationName Request Example
GET /subscription/query/queryByApplicationName/Oracle%20News?offSet=0&batchSize=2 HTTP/1.1 Host: example.com:80 Accept: application/json
Example 5-16 shows a sample queryByApplicationName response.
Example 5-16 queryByApplicationName Response Example
HTTP/1.1 200 OK Content-Type: application/json Date: Wed, 07 Nov 2012 06:56:05 GMT {"subscriptionList":{"subscriptionInfo":[{"applicationName":"Oracle News","subscriberAddress":"tel:1111","status":"UnSubscribePending"},{"applicationName":"Oracle News","subscriberAddress":"tel:1112","status":"Active"}]}}
The queryBySubscriptionID operation retrieves application subscription information for a subscriber based on the subscription ID.
http://host:port/subscription/query/queryBySubscriptionID
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The queryBySubscriptionID request header contains the subscription ID to be queried. The MIME-type for the Content-Type header field is application/json.
The response header includes the request status. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See the chapter on Application Subscription Management in Oracle Communications Services Gatekeeper Communication Service Guide, for more information on error messages.
The request body for queryBySubscriptionID contains the following:
subscriptionInfo. The Services Gatekeeper generated list with the following parameters:
applicationName. String. The name of the subscribed application.
subscriberAddress. String. The MSISDN of the subscriber.
status. String. The subscription status. For example, Pending.
Example 5-17 shows a sample queryBySubscriptionID request.
Example 5-17 queryBySubscriptionID Request Example
GET /subscription/query/queryBySubscriptionId/e4e3cb51-994b-46e1-b0d1-0757a8bca25f HTTP/1.1 Host: example.com:80 Accept: application/json
Example 5-18 shows a sample queryBySubscriptionID response.