This chapter describes the operations in the Application Subscription Management interface of the RESTful facade provided in Oracle Communications Services Gatekeeper.
The Services Gatekeeper Application Subscription Management supports Open Mobile Alliance (OMA) General Service Subscription Management (GSSM) functionality including subscription management, subscription profile access, and subscription validation.
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 RESTful interfaces for managing and querying service subscription status. Applications use the RESTful interfaces to manage subscriptions and query subscription status. Application Subscription Management grants or restricts application access to a subscriber's communication services based 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 Services Gatekeeper Communication Service Reference Guide.
When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of Service Subscription Management interface operations can be found at
http://host:port/subscription/application.wadl
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The Subscribe operation creates a new application service subscription request for a subscriber based on the MSISDN.
http://host:port/subscription
where:
host and port are the host name and port of the system 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 whether the subscription request was successfully created. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See Services Gatekeeper Communication Service Reference Guide, for more information on error messages.
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.htmlThe 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 7-1 shows a sample Subscribe request.
Example 7-1 Subscribe Request Example
POST /subscription HTTP/1.1 Content-Type: application/x-www-form-urlencoded Authorization: Basic YXBwX3VzZXI6YXBwX3VzZXI= Accept: application/json Content-Length: 60 Host: vm-at1:8001 Connection: Keep-Alive User-Agent: Apache-HttpClient/4.1.1 (java 1.5) . applicationName=Mickey News&subscriberAddress=tel:0703322124 .
Example 7-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 system 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 whether the ACR status was successfully changed. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See Services Gatekeeper Communication Service Reference Guide, for more information on error messages.
Example 7-3 shows a sample Unsubscribe request.
Example 7-3 Unsubscribe Request Example
DELETE /subscription/e4e3cb51-994b-46e1-b0d1-0757a8bca25f HTTP/1.1 Host: example.com:80 Accept: application/json
Example 7-4 shows a sample Unsubscribe response.
The Suspend operation suspends an existing service subscription for a subscriber based on the subscription ID.
http://host:port/subscription/suspend/subscriptionID
where:
host and port are the host name and port of the system on which Services Gatekeeper is installed.
subscriptionID is the ID of the subscription to be suspended.
The Suspend request header contains the ID of the subscription to be suspended. The MIME-type for the Content-Type header field is application/json.
The response header indicates whether the subscription was successfully suspended. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See Services Gatekeeper Communication Service Reference Guide, for more information on error messages.
Example 7-5 shows a sample Suspend request.
Example 7-5 Suspend Request Example
PUT /subscription/suspend/e4e3cb51-994b-46e1-b0d1-0757a8bca25f HTTP/1.1 Host: example.com:80 Accept: application/json
Example 7-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 system 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 whether the subscription was successfully removed from being suspended. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See Services Gatekeeper Communication Service Reference Guide, for more information on error messages.
Example 7-7 shows a sample Unsuspend request.
Example 7-7 Unsuspend Request Example
PUT /subscription/unsuspend/e4e3cb51-994b-46e1-b0d1-0757a8bca25f HTTP/1.1 Host: example.com:80 Accept: application/json
Example 7-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 system 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. Services Gatekeeper Communication Service Reference Guide, for more information on error messages.
Example 7-9 shows a sample Notify request.
Example 7-9 Notify Request Example
POST /notifysubscription HTTP/1.1Host: example.com:80
Accept: application/json
Content-Type: application/json
Content-Length: 173
{"subscriptionNotification":{"subscriptionId":
"e4e3cb51-994b-46e1-b0d1-0757a8bca25f","applicationName":"Oracle
News","subscriberAddress":"tel:1111","operation":"Subscribe"}}
Example 7-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 system 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 Services Gatekeeper Communication Service Reference 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 7-11 shows a sample Confirm request.
Example 7-11 Confirm Request Example
PUT /subscription/confirm/e4e3cb51-994b-46e1-b0d1-0757a8bca25f HTTP/1.1 Host: example.com:80 Accept: application/json Content-Type: application/x-www-form-urlencoded Content-Length: 42operation=Subscribe&confirmResult=Approved
Example 7-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 system 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 Services Gatekeeper Communication Service Reference 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 7-13 shows a sample queryBySubscriberAddress request.
Example 7-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 7-14 shows a sample queryBySubscriberAddress response.
Example 7-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":"coderslist",
"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 system 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 Services Gatekeeper Communication Service Reference 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 7-15 shows a sample queryByApplicationName request.
Example 7-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 7-16 shows a sample queryByApplicationName response.
Example 7-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 system 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 Services Gatekeeper Communication Service Reference 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 7-17 shows a sample queryBySubscriptionID request.
Example 7-17 queryBySubscriptionID Request Example
GET /subscription/query/queryBySubscriptionId/e4e3cb51-994b-46e1-b0d1-0757 a8bca25f HTTP/1.1 Host: example.com:80 Accept: application/json
Example 7-18 shows a sample queryBySubscriptionID response.