OTA API Blueprint

What is this

This is a blueprint for how the RESTful API which may one day enable OTA (Over The Air Update) support on WebOS-Ports devices. Over time it will evolve as discussion shapes it into what we need. Eventually should this project become a reality, it will serve as documentation for how the API works.

The Basics

What's included

This API and the feeds it serves will only contain data about packages that are designed to be using during a device OTA. That means that it is not a general purpose repository, but instead contains only core OS related packages. Think along the lines of what you would get should you OTA a stock webOS device that was sold by HP. It will not contain applications made by third party developers, but it will contain core "stock" applications (such as email and the stock web browser) as well as any other packages that WebOS-Ports decides to include as a part of the core distribution for a given device.

Interaction

All requests can include the HTTP standard "If-Modified-Since" header in their requests. This will cause the API to return only information about packages if the data for that package has been updated since that timestamp. All timestamps used in the "If-Modified-Since" header should be in the UTC timezone. Unless otherwise mentioned below, API calls should be assumed to be compatible with the usage of this header.

Retrieving Packages

Following the WebOS-Internals Packaging Standard the IPKG feeds that are returned will include a Location: line indicating a URL that the requested package can be downloaded from.

Valid URI's

The planned valid URL's will include the following:

• http://ota.webos-ports.org/:feed
• http://ota.webos-ports.org/:feed/:devicename
• http://ota.webos-ports.org/:feed/:devicename/:package
• http://ota.webos-ports.org/:feed/:devicename/:package/:version
• http://ota.webos-ports.org/:feed/:devicename/:package/:version/:field

For brevity, throughout the rest of this page, the above will be referred to by their URI ( /:devicename ) rather than their full URL ( http://ota.webos-ports.org/:devicename )

/:feed

General Information

The :feed field can be one of the following, with the access restrictions noted below

:feed	Access Restrictions
dev	Restricted access, developers only (these packages are extremely likely to be broken at any given time)
alpha	General Availability, opt-in
beta	General Availability, opt-in
release	General Availability, default feed for all WebOS-Ports releases

Rarely (if ever) will you want to make an API call against /:feed, you likely want /:feed/:devicename instead.

Access to restricted feeds

All requests to restricted feeds must include the HTTP standard "Authorization" header. This header should be set to a hex_sha1 of the devices IMEI (for phones) or NDUID (for tablets). The devices actual IMEI/NDUID should never be sent to the API server, only the hex_sha1 hashed version. Access to these feeds would require having the hex_sha1 of your devices IMEI/NDUID pre-configured on the API servers for your device to be allowed access to that restricted feed.

In the case of restricted feeds, the Authorization header must also be included when downloading the package from the indicated Location line.

Any requests against a restricted feed that do not include a valid authorization line will return a standard HTTP status code 401 (Unauthorized)

Initially only one restricted feed is planned, but others could be created/removed on-demand for testing different configurations and devices.

HEAD

Returns standatd HTTP headers indicating if a feed at that location exists as well as the last time the feed at that location exists.

GET

Returns a list of all devices that have packages located within this feed (I.E. GET to /beta will list all devices that have beta packages available

PUT

Not Implimented

POST

Not Implimented

/:feed/:devicename

HEAD

Returns standatd HTTP headers indicating if the requested device has packages in the requested feed as well as a timestamp indicating the last time that index was updated located in the HTTP standard Last-Modified header. If the client tracks the timestamp of the last time it successfully performed an OTA update, a HEAD request against this URL would allow for fast and lightweight checks for the availability of new OTA packages.

GET

Returns an IPKG compliant feed index comprised of data from the LATEST versions of all packages available for a particular device.

PUT

Not Implimented

POST

Not Implimented

/:feed/:devicename/:package

HEAD

Returns standatd HTTP headers with data about the requested package, for the requested device within the requested feed such as the timestamp indicating the last time that package was updated located in the HTTP standard Last-Modified header. If the client tracks the timestamp of the last time it successfully updated this particular package, a HEAD request against this URL would allow for fast and lightweight checks for the availability of new versions of this pacakge.

GET

Returns an IPKG compliant feed index comprised of data from the LATEST version of the requested package available for a particular device within the requested feed.

PUT

Not Implimented

POST

Not Implimented

/:feed/:devicename/:package/:version

General information

This request is almost identical to the one above, it allows you to request the same information as above, with all of the same API calls, but for a specific indicated version of the package. Using the keyword "latest" instead of a version number would make this API call identical to above, but you could request data for any version of a package that the API has information on. For most API requests, the keyword "latest" will be utilized

/:feed/:devicename/:package/:version/:field

HEAD

Similar to /:feed/:devicename/:package but instead would return data pertaining to the last time the indicated field was updated etc. This would allow you to, for example, see when the last time a packages description was modified.

GET

Returns a specific field/line from an IPKG compliant feed index comprised of data from the indicated version (normally latest) of the requested package available for a particular device within the requested feed.

PUT

Not Implimented

POST

Not Implimented