Simple Software Update Protocol
Specification Version 0.5
SSUP is a protocol specification for checking and retrieving software updates.
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 <ssup> as the primary element with a version attribute indicating the specification version in the format #.#. See the SSUP XML Schema for a complete specification of the SSUP response objects.
1) Action: software_updates
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.
id (string)
This is the unique id of the software package to be checked for updates. This id is typically assigned by the service to ensure uniqueness.
version (string)
The current version of the software package running on the device. This must be in the format “x.x.x” where the first value is the major release number, the second value is the minor release number and the third value is the maintenance release number.
Example software_updates Action:
id: app-win
version: 1.1
device: we9r8g3409ty349grif34t
session: 348t39ghqi4ho3u4
Example XML Response:
<ssup version="x.x">
<response>
<code>1</code>
<message>Updates available.</message>
<count>1</count>
</response>
<updates>
<update>
<id>app-win</id> [A]
<version>1.1.0</version> [B]
<url>/software_download/app/win/1.1</url> [C]
<digest>elk32l3kjl2krj4kkwrw4</digest> [D]
<digest_algorithm>md5</digest_algorithm> [D]
</update>
...
</updates>
</ssup>
[A] The unique id of the software package. This is typically assigned by the service.
[B] The newer version of the software package. This might not be the newest version, but it should be the most recent version to which the device can be safely updated from its current running version.
[C] The url where the newer software package may be obtained.
[D] The digest of the software package for integrity verification. The digest_algorithm attribute may be one of the following: md5, sha1, sha2
Possible Response Codes:
-1 (unknown error)
-12 (extended error information available)
-24 (missing element)
0 Responses
Stay in touch with the conversation, subscribe to the RSS feed for comments on this post.