Simple Service Administration Protocol
Specification Version 1.0
(this specification is in progress)
SSAP is a protocol specification for administration of a content service.
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 <sctp> as the primary element with a version attribute indicating the specification version in the format #.#. See the SSAP XML Schema for a complete specification of the SSAP response objects.
Action: capabilities
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.
Example capabilities Action:
action url: http://hostname/ssap/capabilities
Example XML Response:
<ssap version=x.x>
<response>
<code>1</code>
<message>Success.</message>
</response>
<capabilities>
<password_length>6-8</password_length> [A]
<password_char>upper,lower,number</password_char> [B]
<rental_duration>2</rental_duration> [D]
<rental_window>30</rental_window> [E]
</capabilities>
</ssap>
[A] The format is #-#, where the first number is an integer between 0 and 50 which represents the minimum number of characters in an acceptable password, and the second number is an integer between 0 and 50 which represents the maximum number of characters in an acceptable password. A value of 0-0 means that no password is necessary.
[B] Contains a comma-separated list of at least one of the following: upper, lower, number. The inclusion of upper indicates that at least one upper case letter must be present in an acceptable password. The inclusion of lower indicates that at least one lower case letter must be present in an acceptable password. The inclusion of number indicates that at least one number must be present in an acceptable password.
[D] Contains an integer indicating the number of calendar days during which a viewer may watch a rented content item after the rental transaction is completed (in case of streaming) or initial successful download of the item occurs (in case of download) or, in the case where a rental_window is defined, after initial successful start of playback of the item occurs.
[E] Contains an integer indicating the number of calendar days during which a viewer may begin the rental period upon initial successful start of playback. If this element is absent or empty, then the client may assume that the rental period begins upon initial successful download of the item, or in the case of streaming, upon rental transaction completion.
Possible Response Codes:
-1 (unknown error)
-12 (extended error information available)
-24 (missing element)
Action: create_account
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”.
captcha_image* (string)
This is the url to the captcha image.
captcha* (string)
This is the viewer translated captcha string.
email (string)
This is the email address identifier for the user associated with the user account.
first_name* (string)
This is the first name identifier for the user associated with the user account.
last_name* (string)
This is the last name identifier for the user associated with the user account.
billing_address* (string)
This is the billing address identifier for the user associated with the user account.
billing_address_line2* (string)
This is the 2nd line billing address identifier for the user associated with the user account.
billing_city* (string)
This is the billing city identifier for the user associated with the user account.
billing_state_prov* (string)
This is the state or province identifier. In the case of the United States, the two letter state code as defined by the U.S Postal Service must be used here. Other cases may be handled as a human readable string.
billing_postal_code* (string)
This is the postal code. In the case of the United States, the format may be either “00000″ or “00000-0000″. If the service does not support the additional 4 digits of a U.S. postal code, then it may discard the additional 4 digits.
billing_country* (string)
This is the two letter country code as defined by ISO 3166.
payment_method* (string)
This may be one of the following: credit_card, invoice, paypal, google_checkout.
payment_account* (string)
This is the payment account number. In the case of credit card it is the credit card number. This may not be necessary in the case of invoice billing method.
payment_account_exp* (string)
This is the expiration of the payment account. The format is “yyyy-mm” or “yyyy-mm-dd” for year, month and day. If the payment method does not require the day component in the expiration, then it may be discarded. This may not be necessary in the case of invoice billing method.
card_type* (string)
These card types are defined by SCTP: visa, mastercard, amex, jcb. Additional card types may be defined by the service. Service-defined types must not conflict with SCTP-defined types. This is only used if billing_method is “credit_card”.
card_security_code* (string)
This is the 3-4 digital security code printed on the credit card. This is only used if billing_method is “credit_card”.
Example create_account Action:
action url: http://hostname.com/sctp/createaccount device: we9r8g3409ty349grif34t session: 348t39ghqi4ho3u4 username: user@domain.com password: ******** captcha_image: http://hostname.com/captcha/342rwekjrl2krl23 captcha: 3kr45 email: user@domain.com first_name: John last_name: Smith billing_address: 123 My Street billing_address_line2: billing_city: San Francisco billing_state_prov: ca billing_postal_code: 94111 billing_country: us payment_method: credit_card payment_account: 1234567890123456 payment_account_exp: 2010-07 card_type: visa card_security_code: 303
Example XML Response:
<ssap version="x.x">
<response>
<code>-24</code>
<message>One or more required form elements are missing.</message>
</response>
<session>348t39ghqi4ho3u4</session>
</ssap>
Possible Response Codes:
1 (success)
-1 (unknown error)
-12 (extended error information available)
-13 (invalid credentials)
-23 (inappropriate value)
-24 (missing element)
Action: account_info
Method: HTTP GET
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”.
result (string)
This is the comma separated list of result fields to be included in the result set. The following fields are defined by SCTP: email, first_name, last_name, billing_address_line2, billing_city, billing_state_prov, billing_postal_code, billing_country, billing_method, payment_account, payment_account_exp, card_type, card_security_code.
Example account_info Request:
action url: http://hostname/sctp/account device: we9r8g3409ty349grif34t session: 348t39ghqi4ho3u4 result: email, first_name, last_name, billing_address_line2, billing_city, billing_state_prov, billing_postal_code, billing_country, billing_method, payment_account, payment_account_exp, card_type, card_security_code
Example XML Response:
<ssap version="x.x">
<response>
<code>1</code>
<message>Your transaction was completed.</message>
</response>
<account>
<email>user@domain.com</email>
<first_name>John</first_name>
<last_name>Doe</last_name>
<billing_address>123 Street</billing_address>
<billing_address_line2></billing_address_line2>
<billing_city>San Jose</billing_city>
<billing_state_prov>ca</billing_state_prov>
<billing_postal_code>95100</billing_postal_code>
<billing_country>us</billing_country>
<payment_method>credit_card</payment_method>
<payment_account>************3456</payment_account>
<payment_account_exp>2010-07</payment_account_exp>
<card_type>visa</card_type>
<card_security_code>303</card_security_code>
</account>
<session>348t39ghqi4ho3u4</session>
</ssap>
Possible Response Codes:
1 (success)
-1 (unknown error)
-2 (device not authorized)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)
Note: Success returns a full set of account fields (same as provided during create account). Element names are camel case without underscores.
Action: update_account
Method: HTTP PUT (or POST with parameter “_method=put” OK)
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”.
new_username* (string)
The new 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.
new_password* (string)
The new 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”.
email* (string)
This is the email address identifier for the user account.
first_name* (string)
This is the first name of the user assigned to the user account.
last_name* (string)
This is the last name of the user assigned to the user account.
billing_address* (string)
This is the billing address identifier of the user account.
billing_address_line2* (string)
This is the 2nd line identifier of the user assigned to the user account.
billing_city* (string)
This is the city identifier used for the user account.
billing_state_prov* (string)
This is the state or province identifier. In the case of the United States, the two letter state code as defined by the U.S Postal Service must be used here. Other cases may be handled as a human readable string.
billing_postal_code* (string)
This is the postal code. In the case of the United States, the format may be either “00000″ or “00000-0000″. If the service does not support the additional 4 digits of a U.S. postal code, then it may discard the additional 4 digits.
billing_country* (string)
This is the two letter country code as defined by ISO 3166.
payment_method* (string)
This may be one of the following: credit_card, invoice, paypal, google_checkout.
payment_account* (string)
This is the payment account number. In the case of credit card it is the credit card number. This may not be necessary in the case of invoice billing method.
payment_account_exp* (string)
This is the expiration of the payment account. The format is “yyyy-mm” or “yyyy-mm-dd” for year, month and day. If the payment method does not require the day component in the expiration, then it may be discarded. This may not be necessary in the case of invoice billing method.
card_type* (string)
These card types are defined by SCTP: visa, mastercard, amex, jcb. Additional card types may be defined by the service. Service-defined types must not conflict with SCTP-defined types. This is only used if billing_method is “credit_card”.
card_security_code* (string)
This is the 3-4 digital security code printed on the credit card. This is only used if billing_method is “credit_card”.
Example update_account Action:
action url: http://hostname.com/sctp/updateaccount device: we9r8g3409ty349grif34t session: 348t39ghqi4ho3u4 new_username: newuser@domain.com new_password: <********* email: user@domain.com first_name: John last_name: Doe billing_address: 123 Street billing_address_line2: billing_city: San Jose billing_state_prov: ca billing_postal_code: 94111 billing_country: us payment_method: credit_card payment_account: 1234567890123456 payment_account_exp: 2010-07 card_type: visa card_security_code: 303
Example XML Response:
<ssap version=x.x>
<response>
<code>1</code>
<message>Your transaction was completed.</message>
</response>
<account>
<new_username>newuser@domain.com</new_username>
<new_password>*********</new_password>
<new_digest>sha1</new_digest>
<email>user@domain.com</email>
<first_name>John</first_name>
<last_name>Doe</last_name>
<billing_address>123 Street</billing_address>
<billing_address_line2></billing_address_line2>
<billing_city>San Jose</billing_city>
<billing_state_prov>ca</billing_state_prov>
<billing_postal_code>95100</billing_postal_code>
<billing_country>us</billing_country>
<payment_method>credit_card</payment_method>
<payment_account>************3456</payment_account>
<payment_account_exp>2010-07</payment_account_exp>
<card_type>visa</card_type>
<card_security_code>303</card_security_code>
</account>
<session>348t39ghqi4ho3u4</session>
</ssap>
Possible Response Codes:
1 (success)
-1 (unknown error)
-12 (extended error information available)
-13 (invalid credentials)
-14 (device not personalized)
-24 (missing element)
Note: Any error will cancel the update.
Action: update_device
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.
manufacturer* (string)
This is a case-insensitive alphanumeric unique (within the service) id which may include only “-” and “.” punctuation and no spaces. This should represent the manufacturer of the device.
device_model* (string)
This is a case-insensitive alphanumeric unique (within the manufacturer scope) id which may include only “-” and “.” punctuation and no spaces.
platform* (string)
This is a case-insensitive alphanumeric unique (within the service) id which may include only “-” and “.” punctuation and no spaces.
platform_version* (string)
This must be in the format “x”, “x.x” or “x.x.x” where each section “x” may be any alphanumeric value. In order to support SSUP properly, higher values must represent higher versions.
software* (string)
This is a case-insensitive alphanumeric unique (within the service) id which may include only “-” and “.” punctuation and no spaces.
software_version* (string)
This must be in the format “x”, “x.x” or “x.x.x” where each section “x” may be any alphanumeric value. In order to support SSUP properly, higher values must represent higher versions.
label* (string)
This is the user created name which may contain any character.
Example update_device Action:
action url: http://hostname.com/sctp/update_device manufacturer: the-big-company device_model: tv-100 software: tv-app software_version: 3.4.0
Example XML Response:
<sctp version="x.x">
<response>
<code>1</code>
<message>Device info updated.</message>
</response>
<session>348t39ghqi4ho3u4</session>
</sctp>
Possible Response Codes:
-1 (unknown error)
-12 (extended error information available)
-13 (invalid credentials)
-24 (missing element)
Response Code Glossary:
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 content 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 subscribed 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 deauthorize 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 (device not personalized)
Suggested description message: ‘This device is not yet registered with the service. Please ensure your Internet connection is working correctly. Device registration automatically occurs.’
-15 (not subscribed)
Suggested description message: ‘You are currently subscribed to this channel or show.’
-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 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.’
Note: For extended error information there is an optional element “error” which is a sibling to code and message elements, containing additional textual error data for the client to display.
0 Responses
Stay in touch with the conversation, subscribe to the RSS feed for comments on this post.