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.
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.
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.
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.
The API server should sit behind an HTTP caching mechanism (I.E. Varnish) with a very long (I.E. 24 hour) cache expiration time. The API server should intelligently expire the cached version of an object should that objects data change. This allows for a good balance of high speed while still ensuring that API data is always up-to-date.
The planned valid URL's will include the following:
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 )
The :feed field can be one of the following, with the access restrictions noted below
|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|
The feed that your device is using could potentially be managed through a setting in Tweaks. Devices without Tweaks installed would default to the release feed, but devices with Tweaks would be able to select the other feeds. If we utilize Tweaks for feed selection, it should either include information clearly stating that the dev feed is restricted, or hide that feed from tweaks and require some other action in order to enable the dev feed selection as most devices will not have access to that feed.
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.
Returns standatd HTTP headers indicating if a feed at that location exists as well as the last time the feed at that location exists.
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
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.
Returns an IPKG compliant feed index comprised of data from the LATEST versions of all packages available for a particular device.
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.
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.
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
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.
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.