ubuntu-appstore-developers team mailing list archive

["Alejandro J. Cura" <alejandro.cura@xxxxxxxxxxxxx>]

On Wed, Jul 3, 2013 at 9:07 AM, James Tait <james.tait@xxxxxxxxxxxxxx> wrote:
> 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.

I don't think we have any use for the responseHeader on the client
side, and smaller json sounds like win.
+1 from our side.

cheers,
-- 
alecu