ubuntu-appstore-developers team mailing list archive

[James Tait <james.tait@xxxxxxxxxxxxx>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Greetings!  With things moving so quickly, it's past time for the
latest update!

Schema Changes
==============
 * Addition of the last_updated field to Package resources.  This is
   the date of the last binary upload for a Package.
 * Addition of the content field to Package resources, also visible in
   search results.  The value of this field will be "scope" if the
   Package contains just a scope, or "application" if the Package
   contains just an application, or a combination of an application and
   a scope.
 * Addition of the department field to Highlight resources, to link a
   given highlight to one or more Departments (e.g. "Top Games").
 * Changed the department property of Package resources to be a list of
   Department slugs (unique IDs), least specific first.
 * New Recommendation resource, returned in search responses, suggesting
   alternative packages that may be related to the user's search.

API Changes
===========
 * The root API resource (/api/v1) has now been implemented.  For plain
   JSON responses it will return a simple list of links to the various
   URL endpoints; for HAL+JSON [0] responses it will serve as a
   "bootstrap" call, returning the aforementioned links (as URI
   templates, where appropriate), as well as a hierarchy of departments
   and a list of highlights.
 * Search responses for HAL+JSON clients will now include
   recommendations, as mentioned above, embedded with the
   "clickindex:recommendation" relation type.
 * Department resources for HAL+JSON clients will include
   department-specific highlights, embedded with the
   "clickindex:highlight" relation type.
 * Package resources are now available as HAL+JSON documents - this
   completes the HAL+JSON coverage of resources.

Coming Changes
==============
When we set out on this journey, we did so with a fairly simplistic
mission: type keywords into a text field, and have package metadata
returned.  As time has gone on, the requirements have been fleshed out
and our understanding of the problem has grown.  More resource types
have been added; filtering based on device architecture, supported
frameworks and geographic location; and, as the number of packages in
the Index - and thus the size of the potential result set - has grown,
pagination.

As we've added more features, it has become more of a maintenance
burden to write two representations of each resource and keep our code
clean.  Since people have taken their own time to write software that
uses the API, we've tried hard to maintain backward compatibility with
the endpoints we know are in use (search and package), and although
the API isn't yet considered stable we love the fact that people are
experimenting with it, but going forward new features will *only*
support application/hal+json. Furthermore, we plan to remove support
for application/json at the end of July.

Unfortunately, this means that some of the work of keeping software
that uses the Index working falls back to the client developers.  The
full details of our responses are available in the wiki page [1], but
the short and skinny is:

Package (including those embedded in Search responses):
  * The link to a package resource is now within the `_links`
    property of the package, with the `self` reltype, replacing
    `resource_url`.
    * i.e. what was `package['resource_url']` is now
      `package['_links']['self']['href']`.
    * This follows for all resources - search, package, highlights,
      departments, recommendations all have a self href.

Search:
  * Search results are limited to 100 items by default.
    * Use `size` and `page` parameters (e.g. `?size=9999&page=1`) to
      overcome this, though we may still impose limits if it is
      abused.
  * Pagination links are in the `_links property`, using IANA-defined
    reltypes.
    * i.e. `response['_links']` contains 'first', 'last', 'next' and
      'prev' alongside 'self', where appropriate.
  * Package objects are embedded with a `clickindex:package` reltype.
    * i.e. `response['_embedded']['clickindex:package']` now contains
      your search results.

The changes required *shouldn't* be too significant, and we think are
far outweighed by the overall benefits to be gained from utilising a
standardised format - like client libraries [2], API-agnostic browsing
[3] and better discoverability.

As always, the API documentation is on the Ubuntu Wiki, and will
continue to be updated as we flesh things out.

Until next time!

JT

[0] http://tools.ietf.org/html/draft-kelly-json-hal-06
[1] https://wiki.ubuntu.com/AppStore/Interfaces/ClickPackageIndex
[2] https://github.com/mikekelly/hal_specification/wiki/Libraries
[3] https://github.com/mikekelly/hal-browser
- -- 
James Tait, BSc. | https://launchpad.net/~jamestait/
Software Engineer, Canonical Online Services, Web and Ops Team
Ubuntu - Linux for human beings | www.ubuntu.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iEYEARECAAYFAlPFcQ0ACgkQyDo4xMNTLiZEJACgvEQzrQxYH1lUb9gdE4h+bMKJ
Zc0AoIBbiXyxXi6KcnIbFMK5oON8uOKx
=4Ahp
-----END PGP SIGNATURE-----