ubuntu-appstore-developers team mailing list archive

[James Tait <james.tait@xxxxxxxxxxxxx>]

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

It's been far too long since our last status update, and there's much
to tell you about!

First and foremost, we switched our index back-end from Solr to
Elasticsearch.  This should have been mostly transparent to end users,
but allows us to more easily scale out to handle greater load.

Schema Changes
==============
None!


API Changes
===========
Client platform properties (i.e. supported frameworks and
architecture) have been deprecated as query parameters and moved to
request headers instead.  This helps to keep the query string clean -
it only contains things the user entered.

Example:

GET /api/v1/search HTTP/1.1
Host: search.apps.ubuntu.com:443
X-Ubuntu-Frameworks: ubuntu-sdk-13.10,ubuntu-sdk-14.04
X-Ubuntu-Architecture: armhf
Accept: application/json


Field specification has finally been implemented.  When querying the
/search and /package endpoints, you can now add a fields parameter
listing the fields you want to retrieve in the response.

Example:
https://search.apps.ubuntu.com/api/v1/search?q=flappy&fields=name,resource_url


Pagination has been added to the search endpoint.  You can now specify
page and size parameters to retrieve the response in chunks.  The
default page size is 100 results.

Example:
https://search.apps.ubuntu.com/api/v1/search?q=flappy&page=1&size=100


Since day one we've tried to keep the API browsable, but when adding
the pagination feature we realised that the list response of the
search endpoint didn't really give us anywhere to insert the
pagination links.  Rather than stuff them away in a response header or
invent our own format for representing them, we have adopted the draft
hal+json [0] format with well-known link relations.  To enable this
behaviour, pass the Accept header in the request with the
`application/hal+json` content type.

Example:

GET /api/v1/search HTTP/1.1
Host: search.apps.ubuntu.com:443
X-Ubuntu-Frameworks: ubuntu-sdk-13.10,ubuntu-sdk-14.04
X-Ubuntu-Architecture: armhf
Accept: application/hal+json


Finally, to be consistent with the /departments endpoint, we have
moved /highlight to /highlights.  In practice, nothing was using this
endpoint yet anyway, so better to move it now than later.

Coming Changes
==============
Support for the hal+json format will be rolled out across the board.
We also demoed a preview of automatic localisation of search and
package results based on the Accept-Language request header at the
Client Sprint in Malta last week.  Also, the root resource at /api/v1
is going to become useful and will be queried by the apps scope to
bootstrap the apps searching experience.


As always, the API documentation is on the Ubuntu Wiki [1], 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
- -- 
James Tait, BSc. | https://launchpad.net/~jamestait/
Software Engineer, Canonical Online Services
Ubuntu - Linux for human beings | www.ubuntu.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iEYEARECAAYFAlOIvlAACgkQyDo4xMNTLibrAQCg/FKBGzXId5UYfMj4eq+BevsZ
k+QAnjeNyB9SxHmCXoC55XXSd7xu/b0i
=geSo
-----END PGP SIGNATURE-----