ubuntu-appstore-developers team mailing list archive

[James Tait <james.tait@xxxxxxxxxxxxxx>]

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

Hi all,

A few more thoughts on the Click Index API.  We're looking to support
localised responses something like this:

===
GET /api/v1/package/some_id HTTP/1.1
Host: search.apps.ubuntu.com
Accept-Language: en

- ---
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Vary: Accept-Language
ETag: abc123

{
  ...
}
===

Currently the response body looks almost like the Solr response, and
consists of a responseHeader object with a bunch of metatadata mostly
about the request, and the a response object with some metadata and a
list of docs:

===
{
  "responseHeader":{
    "status":0,
    "QTime":1,
    "params":{
      "fl": "id,title,description,price,icon_url",
      "indent":"on",
      "start":"0",
      "q":"id:2",
      "wt":"json",
      "version":"2.2",
      "rows":"1"
    }
  },
  "response":{
    "numFound":1,
    "start":0,
    "docs":[
      {
        "id": "2",
        ...
      }
    ]
  }
}
===

When we generate the ETag, we don't want changes in responseHeader
(e.g. that QTime property) to alter the hash - we're only interested
in changes to the response object.  That's easy enough to do, but I
was wondering if the responseHeader is of any use on the client side
at all.  Instead, I was thinking of something more like:

===
GET /api/v1/search?q=rubbish
Host: search.apps.ubuntu.com
Accept-Language: en

- ---
HTTP/1.1 204 No Content
Content-Type: application/json; charset=utf-8
Vary: Accept-Language
ETag: abc123
===
GET /api/v1/search?q=awesome
Host: search.apps.ubuntu.com
Accept-Language: en

- ---
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Vary: Accept-Language
ETag: abc123

[
  {
    "id": "an_id",
    "title": "Awesome App",
    "description": "This app does magic.",
    "icon_url": "http://exmaple.com/default_icon.png";,
    "resource_url": "http://search.apps.ubuntu.com/api/v1/package/an_id";
  }
]
===
GET /api/v1/package/an_id HTTP/1.1
Host: search.apps.ubuntu.com
Accept-Language: en

- ---
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Vary: Accept-Language
ETag: abc123

{
  "id": "an_id",
  ... /* lots more fields */
}
===
GET /api/v1/package/an_id HTTP/1.1
Host: search.apps.ubuntu.com
Accept-Language: en
If-None-Match: abc123
- ---
HTTP/1.1 304 Not Modified
Vary: Accept-Language
ETag: abc123
Date: Date: Wed, 03 Jul 2013 06:25:24 GMT
===

With some references to self and other resources in there.  Much less
verbose, which will be a bonus on mobile devices.  I'd appreciate any
thoughts on this approach.

Cheers,

JT
- -- 
- ---------------------------------------+--------------------------------
James Tait, BSc                        |    xmpp:jayteeuk@xxxxxxxxxxxxxx
Programmer and Free Software advocate  |        Tel: +44 (0)870 490 2407
- ---------------------------------------+--------------------------------

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)
Comment: Using GnuPG with undefined - http://www.enigmail.net/

iEYEARECAAYFAlHUE/AACgkQyDo4xMNTLiYBgACg6Oqj8+ID4QszsG+bAJhyhoz2
2LEAn3MSGCX2+PmDWzKhKWr9cLHrT1Z2
=QxYv
-----END PGP SIGNATURE-----