Simple Content Subscription Protocol
Specification Version 0.5
SCSP is a protocol specification for content subscription.
Like all SIMS protocols, this standard defines a set of resources or “actions” in the form of an HTTP GET (or POST) request which returns a response in XML or JSON format. The HTTP method does not strictly conform to REST conventions, as GET may represent retrieval, creation, modification or deletion of data on the server. POST is required only when the client is posting a large amount of data to the server, such as a bulk load of content metadata. All actions are assumed to use HTTP GET unless marked otherwise.
The location of the RADL of a SIMS protocol is discovered via the SCDL service description page. Therefore the only URL which a device must know ahead of time is the location of the SCDL service description page, and this may be posted on an informational page on the service’s web site. The recommended URL for such a page is http://hostname/sims. This makes it easy for anyone to figure out how to connect to your service.
Note: Each RADL of a SIMS protocol may define a resource path with implicit SIMS parameter values, meaning some SIMS parameter values are not included in the request but they are assumed in the path. Such resources defined in a RADL of a SIMS protocol implementation: a) must include a “sims:action” attribute within the method element where applicable, and the attribute value is the name of the SIMS action, b) must include a “sims:implicit” element within the request element where applicable, and its value is the value of an implied SIMS param value and its “param” attribute contains the implicit SIMS param name, c) must always use SIMS parameter names where applicable, and d) should include a “doc” element which contains one or more example request URIs each with a description of the equivalent SIMS action and parameters.
Example SIMS action URL with implicit parameter values:
http://hostname/browse/shows/234/seasons
This example URL is for an SCBP “search” action, and it returns a list of seasons for the show with an id value of 234. In this example, “234″ is an explicit value for the show id parameter. In this case the id value is passed as part of the url path, instead of a query parameter. The “/seasons” section of the url path represents an implicit parameter value with the meaning: type=”seasonal_series”. The meaning of this implicit parameter value would be discovered via the service’s SCBP WADL.
Each response must include <scsp> as the primary element with a version attribute indicating the specification version in the format #.#. See the SCSP XML Schema for a complete specification of the SCSP response objects.
1) Action: capabilities
Parameters (* is optional):
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, service should assume xml.
Example capabilities Action:
Example XML Response:
<scsp version=x.x>
<response>
<code>1</code>
<message>Success.</message>
</response>
<capabilities>
<subscription_duration>45</subscription_duration> [A]
<renewal_period>15</renewal_period> [B]
</capabilities>
</scsp>
[A] The number of calendar days during which the subscription is active. After this period the subscription will expire.
[B] The number of calendar days prior to the subscription expiration during which the service will allow renewal requests for the subscription. For example, if a subscription_duration is 45 and the renewal_period is 15, then 30 days after the subscription starts the service will allow a renewal request to avoid expiration. The renewal will result in a new subscription for 45 days starting from the time of renewal. Thus, the perceived subscription duration is 30 days (monthly) with a 15 day grace period for renewal.
Possible Response Codes:
-1 (unknown error)
-12 (extended error information available)
-24 (missing element)
2) Action: subscribe
Parameters (* is optional):
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session.
username* (string)
The username of the account. Not needed if session id is used. This can be any alphanumeric string including any characters which are allowed in an Internet email address. In some cases the service may allow "anonymous" with no password.
password* (string)
The password for the account. Not needed if session id is used. This can be any alphanumeric string including "!@#$%^&*()_+-=<>.{}[]|". It may be hashed or encrypted depending upon the digest parameter. This may be empty if username is "anonymous".
digest* (string)
This may be one of the following: md5, sha1, sha2, none. If absent or empty, then service must assume none.
type (string)
One of the following: channel, show, radio_station
id (string)
This string value is used to represent the ID for the content the user is subscribing to.
Example subscribe Action:
device: we7r8z4567ty349grif34t
session: 348t39ghqi4ho3u4
type: episodes
id: 23446
Example XML Response:
<scsp version=x.x>
<response>
<code>1</code>
<message>Your transaction was completed.</message>
</response>
<drm type="marlinbb">
...
</drm>
<session>348t39ghqi4ho3u4</response>
</sctp>
Possible Response Codes:
-1 (unknown error)
-3 (content not valid)
-6 (already subscribed)
-8 (user not logged in)
-12 (extended error information available)
-24 (missing element)
Note: In the case of protected content, success returns a DRM action token to acquire the subscription node.
3) Action: unsubscribe
Parameters (* is optional):
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session.
username* (string)
The username of the account. Not needed if session id is used. This can be any alphanumeric string including any characters which are allowed in an Internet email address. In some cases the service may allow "anonymous" with no password.
password* (string)
The password for the account. Not needed if session id is used. This can be any alphanumeric string including "!@#$%^&*()_+-=<>.{}[]|". It may be hashed or encrypted depending upon the digest parameter. This may be empty if username is "anonymous".
digest* (string)
This may be one of the following: md5, sha1, sha2, none. If absent or empty, then service must assume none.
type (string)
One of the following: channel, show, radio_station
id (string)
This string value is used to represent the ID for the content the user is subscribing to.
Example unsubscribe Action:
device: we7r8z4567ty349grif34t
session: 348t39ghqi4ho3u4
type: episodes
id: 244086
Example XML Response:
<scsp version=x.x>
<response>
<code>1</code>
<message>Your transaction was completed</message>
</response>
<drm type="marlinbb">
...
</drm>
</scsp>
Possible Response Codes:
1 (success)
-1 (unknown error)
-3 (content not valid)
-8 (user not logged in)
-12 (extended error information available)
-15 (renewal too early)
-24 (missing element)
Note: In the case of protected content, success returns a DRM action token to purge the subscription node.
4) Action: subscriptions
Parameters (* is optional):
This specifies the desired output format of the response. Can be one of the following: json, xml. If absent, then service assumes xml.
device (string)
The device id of the device performing the action.
session* (string)
The session id of the account authenticated session.
username* (string)
The username of the account. Not needed if session id is used. This can be any alphanumeric string including any characters which are allowed in an Internet email address. In some cases the service may allow "anonymous" with no password.
password* (string)
The password for the account. Not needed if session id is used. This can be any alphanumeric string including "!@#$%^&*()_+-=<>.{}[]|". It may be hashed or encrypted depending upon the digest parameter. This may be empty if username is "anonymous".
type (string)
One of the following: channel, show, radio_station, subscription
This is the unique (within the service) id of the item subscribed to or the id of the subscription itself. If this is empty, then the service must return data for all active subscriptions associated with the account.
digest* (string)
This may be one of the following: md5, sha1, sha2, none. If absent or empty, then service must assume none.
Example subscriptions Action:
device: we7r8z4567ty349grif34t
session: 348t39ghqi4ho3u4
Example XML Response:
<scsp version=x.x>
<response>
<code>1</code>
<message>Your transaction was completed</message>
<count>5</count>
</response>
<subscriptions>
<subscription>
<id>6<id>
<expiration>2007-04-28</expiration>
<renew>/transact/subscribe_channel/6</renew>
<type>Channel</type>
<title>Cartoon Network</title>
</subscription>
<subscription>
<id>7<id>
<expiration>2008-05-31</expiration>
<renew>/transact/subscribe_channel/7</renew>
<type>Channel</type>
<title>CBS</title>
</subscription>
⋮
</subscriptions>
<drm type="marlinbb"> [A]
...
</drm>
</scsp>
[A] In the case of protected content, success returns any DRM data necessary to acquire the subscription nodes listed in the response. If the service allows a renewal grace period, and the account has entered that grace period (which is some portion of time before the actual expiration of the subscription), then the service should return the DRM data needed to acquire a renewed subscription. In such as case the DRM data should allow for a subscription period which includes the grace period. For example a 30-day subscription may actually deliver DRM data for a 45-day subscription, allowing for a 15 day grace period for renewal.
Also, a service may set the expiration date of subsequent subscription nodes to be the period of time until the next account billing cycle, instead of a consistent period of time from the point of renewal. For example, a 45-day subscription with a 15-day renewal period may be renewed 35 days from the last renewal, and in this case the service may deliver a 40-day subscription in order to keep the account billing cycle on the same day each month. There is no requirement for how the service determines subscription durations upon each renewal. This is a service implementation choice.
Possible Response Codes:
-1 (unknown error)
-8 (user not logged in)
-12 (extended error information available)
-24 (missing element)
Response Code Glossary (see SCTP for more codes):
Suggested description message: 'Your transaction was completed.'
-1 (unknown error)
Suggested description message: 'There was an unknown error.'
-2 (device not authorized)
Suggested description message: 'This device is not currently authorized for your account.'
-3 (content not valid)
Suggested description message: 'The item you requested is not valid.'
-4 (content not available)
'Suggested description message: 'The item you requested is not available.'
-5 (already purchased)
Suggested description: 'You have already purchased this content.'
-6 (already subscribed)
Suggested description message: 'You have already subscribes to this content.'
-7 (user not authorized)
Suggested description message: 'Sorry, you are not currently subscribed to this channel or show, or you have not purchased or rented this item. Please subscribe, purchase or rent this item.'
-8 (user not logged in)
Suggested description message: 'You are not currently logged in. Please log in.'
-9 (device already authorized)
Suggested description messages: 'This device is already authorized for your account.'
-10 (device limit exceeded)
Suggested description message: 'You have already reached the maximum number of authorized devices for your account. You can de-authorize a device in order to authorize this device.'
-11 (user already registered)
Suggested description message: 'You are already registered.'
-12 (extended error information available)
Suggested description message: 'There is more information available for this error.'
-13 (invalid credentials)
Suggested description message: 'The username and password entered is not valid. Please re-enter your username and password.'
-14 (not subscribed)
Suggested description message: 'You are not currently subscribed to this channel or content.'
-15 (renewal too early)
Suggested description message: 'Your current subscription term is still valid. You do not need to renew your subscription at this time.'
-16 (already rented)
Suggested description message: 'You have already rented this item.'
-17 (input absent)
Suggested description: 'There is an input missing. Please fill in all required information.'
-18 (gateway failure)
Suggested description message: 'The Payment Gateway is currently unavailable. Please try again later.'
-19 (payment failure)
Suggested description message: 'Your payment could not be processed. Please try again with a valid payment method.'
-20 (transaction denied)
Suggested description message: Sorry, you can only purchase 5 individual episodes with this press account.'
-21 (device location restricted)
Suggested description message: 'The device you are trying to authorize does not appear to be located in the appropriate region.'
-22 (inactive account login)
Suggested description message: 'This account is not yet active. Please activate this account before attempting to log in.'
-23 (inappropriate value)
Suggested description message: 'One or more form elements contain an inappropriate value.'
-24 (missing element)
Suggested description message: 'One or more required form elements are missing.'
0 Responses
Stay in touch with the conversation, subscribe to the RSS feed for comments on this post.