Difference between revisions of "OTA API Blueprint"
(→GET) |
|||
| (11 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
= What is this = | = 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 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 = | = The Basics = | ||
== What's included == | == What's included == | ||
| − | This API and the feeds it serves will only contain data about packages that are designed to be using during a | + | This API and the feeds it serves will only contain data about packages that are designed to be using during a arch 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 arch 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 arch. |
== Interaction == | == Interaction == | ||
| Line 13: | Line 13: | ||
== Geographic Mirrors == | == Geographic Mirrors == | ||
| − | The API server can maintain a list of mirrors that are offered by volunteers along with a value specifying what geographic region that mirror is located in. This mirror data can be used to intelligently deliver a | + | The API server can maintain a list of mirrors that are offered by volunteers along with a value specifying what geographic region (continent) that mirror is located in. This mirror data can be used to intelligently deliver a 302 redirect to download a package from that is geographically close to the device going through the OTA. All devices should verify a hash (likely MD5) of the package they download against an MD5 hash retreived from the API server (which is under our control). This will ensure that packages retrieved from a volunteer mirror are unaltered and intact. |
= Valid URI's = | = Valid URI's = | ||
| Line 19: | Line 19: | ||
*[[#/:feed|http://ota.webos-ports.org/:feed]] | *[[#/:feed|http://ota.webos-ports.org/:feed]] | ||
| − | *[[#/:feed/: | + | *[[#/:feed/:arch|http://ota.webos-ports.org/:feed/:arch]] |
| − | *[[#/:feed/: | + | *[[#/:feed/:arch/:package|http://ota.webos-ports.org/:feed/:arch/:package]] |
| − | *[[#/:feed/: | + | *[[#/:feed/:arch/:package/:version|http://ota.webos-ports.org/:feed/:arch/:package/:version]] |
| − | *[[#/:feed/: | + | *[[#/:feed/:arch/:package/:version/:field|http://ota.webos-ports.org/:feed/:arch/:package/:version/:field]] |
| − | For brevity, throughout the rest of this page, the above will be referred to by their URI ( /: | + | For brevity, throughout the rest of this page, the above will be referred to by their URI ( /:feed ) rather than their full URL ( |
| − | http://ota.webos-ports.org/: | + | http://ota.webos-ports.org/:feed ) |
== /:feed == | == /:feed == | ||
| Line 48: | Line 48: | ||
|} | |} | ||
| − | The feed that your | + | The feed that your arch 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/: | + | Rarely (if ever) will you want to make an API call against /:feed, you likely want /:feed/:arch instead. |
=== Access to restricted feeds === | === Access to restricted feeds === | ||
| Line 60: | Line 60: | ||
Any requests against a restricted feed that do not include a valid authorization line will return a standard HTTP status code 401 (Unauthorized) | 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. | + | Initially only one restricted feed is planned, but others could be created/removed on-demand for testing different configurations and archs/devices. |
=== HEAD === | === HEAD === | ||
| Line 66: | Line 66: | ||
=== GET === | === GET === | ||
| − | Returns a list of all | + | Returns a list of all archs that have packages located within this feed (I.E. GET to /beta will list all archs that have beta packages available |
=== PUT === | === PUT === | ||
| − | Not | + | Not Implemented |
=== POST === | === POST === | ||
| − | Not | + | Not Implemented |
| − | == /:feed/: | + | == /:feed/:arch == |
=== General Information === | === General Information === | ||
| − | A GET request to /:feed/: | + | A GET request to /:feed/:arch/Packages{,.gz} will return the same data as would a normal IPKG feed. This will allow the API to maintain backwards-compatibility with existing IPKG tools. |
| − | Device names could be "all", a specific architacture, or a machine architecture. See http://build.webos-ports.org/openwebos-ports/ipk/ for example " | + | Device names could be "all", a specific architacture, or a machine architecture. See http://build.webos-ports.org/openwebos-ports/ipk/ for example "arch" values. |
=== HEAD === | === HEAD === | ||
| − | Returns standatd HTTP headers indicating if the requested | + | Returns standatd HTTP headers indicating if the requested arch 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 === | === GET === | ||
| − | Returns | + | Returns list of all packages available for a given architecture within a given feed along with the different versions of those packages. |
=== PUT === | === PUT === | ||
| − | Not | + | Not Implemented |
=== POST === | === POST === | ||
| − | Not | + | Not Implemented |
| − | == /:feed/: | + | == /:feed/:arch/:package == |
=== HEAD === | === HEAD === | ||
| − | Returns standatd HTTP headers with data about the requested package, for the requested | + | Returns standatd HTTP headers with data about the requested package, for the requested arch 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 === | === GET === | ||
| − | Returns a 302 redirect to a mirror URL where the package can be downloaded from. If a geographic region can be determined for a | + | ==== package ==== |
| + | If a request is made to a package without the .ipk extension, the control file information about that package will be returned, along with a list of previous versions of that package which will link to information specific to that version. There will be direct download links on these pages to the currently viewed version. | ||
| + | |||
| + | ==== package.ipk ==== | ||
| + | Returns a 302 redirect to a mirror URL where the package can be downloaded from. If a geographic region can be determined for a arch requesting the package, the API will makes it's best effort to deliver a 302 redirect to a mirror that is geographically close to the arch. If the API is unable to determine a geographic region for the arch, it will return a 302 to a random mirror from it's pool of available mirrors. | ||
| + | |||
| + | ==== Pacakges keyword ==== | ||
| + | If a request is made to the package name Packages or Packages.gz an ipkg compatible Packages index file is returned, this file will be delivered gzippped if it has the .gz extension | ||
=== PUT === | === PUT === | ||
| − | Not | + | Not Implemented |
=== POST === | === POST === | ||
| − | Not | + | Not Implemented |
| − | == /:feed/: | + | == /:feed/:arch/:package/:version == |
=== General information === | === 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 | 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/: | + | == /:feed/:arch/:package/:version/:field == |
=== HEAD === | === HEAD === | ||
| − | Similar to /:feed/: | + | Similar to /:feed/:arch/: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 === | === 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 | + | 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 arch within the requested feed. |
=== PUT === | === PUT === | ||
| − | Not | + | Not Implemented |
=== POST === | === POST === | ||
| − | Not | + | Not Implemented |
Latest revision as of 20:41, 4 October 2012
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 arch 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 arch 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 arch.
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.
Caching
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.
Geographic Mirrors
The API server can maintain a list of mirrors that are offered by volunteers along with a value specifying what geographic region (continent) that mirror is located in. This mirror data can be used to intelligently deliver a 302 redirect to download a package from that is geographically close to the device going through the OTA. All devices should verify a hash (likely MD5) of the package they download against an MD5 hash retreived from the API server (which is under our control). This will ensure that packages retrieved from a volunteer mirror are unaltered and intact.
Valid URI's
The planned valid URL's will include the following:
- http://ota.webos-ports.org/:feed
- http://ota.webos-ports.org/:feed/:arch
- http://ota.webos-ports.org/:feed/:arch/:package
- http://ota.webos-ports.org/:feed/:arch/:package/:version
- http://ota.webos-ports.org/:feed/:arch/:package/:version/:field
For brevity, throughout the rest of this page, the above will be referred to by their URI ( /:feed ) rather than their full URL ( http://ota.webos-ports.org/:feed )
/: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 |
The feed that your arch 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/:arch 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 archs/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 archs that have packages located within this feed (I.E. GET to /beta will list all archs that have beta packages available
PUT
Not Implemented
POST
Not Implemented
/:feed/:arch
General Information
A GET request to /:feed/:arch/Packages{,.gz} will return the same data as would a normal IPKG feed. This will allow the API to maintain backwards-compatibility with existing IPKG tools. Device names could be "all", a specific architacture, or a machine architecture. See http://build.webos-ports.org/openwebos-ports/ipk/ for example "arch" values.
HEAD
Returns standatd HTTP headers indicating if the requested arch 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 list of all packages available for a given architecture within a given feed along with the different versions of those packages.
PUT
Not Implemented
POST
Not Implemented
/:feed/:arch/:package
HEAD
Returns standatd HTTP headers with data about the requested package, for the requested arch 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
package
If a request is made to a package without the .ipk extension, the control file information about that package will be returned, along with a list of previous versions of that package which will link to information specific to that version. There will be direct download links on these pages to the currently viewed version.
package.ipk
Returns a 302 redirect to a mirror URL where the package can be downloaded from. If a geographic region can be determined for a arch requesting the package, the API will makes it's best effort to deliver a 302 redirect to a mirror that is geographically close to the arch. If the API is unable to determine a geographic region for the arch, it will return a 302 to a random mirror from it's pool of available mirrors.
Pacakges keyword
If a request is made to the package name Packages or Packages.gz an ipkg compatible Packages index file is returned, this file will be delivered gzippped if it has the .gz extension
PUT
Not Implemented
POST
Not Implemented
/:feed/:arch/: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/:arch/:package/:version/:field
HEAD
Similar to /:feed/:arch/: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 arch within the requested feed.
PUT
Not Implemented
POST
Not Implemented