Apps/AITC

This document specifies Apps-In-The-Cloud (AITC), a service for storing a user's list of Open Web Apps. This is meant to supersede the AppSync Spec.

Overview

The AITC Service is considered authoritative for the user's list of Web Apps and Device Information. In general, a client can safely overwrite its list of apps with that provided by the server, though it will rarely need to be so blunt. Beyond the list of apps and specific per-device configuration, the AITC Service does not store data for which it is not authoritative. For example, it stores only an app's manifest URL, not its whole manifest.

A few assumptions are made in this design:

adding/removing/reorganizing apps is a rare occurrence compared to turning on a device.
if an app is unavailable, it is okay to temporarily fail to display it to the user in her list of apps.

Document Formats

Documents are JSON.

App

{
   origin: "https://example.com",
   manifestURL: "/foo/bar.manifest",
   installOrigin: "https://marketplace.mozilla.org",
   installedTime: 1330535996745,
   receipts: ["...", "..."]
}

manifestURL is relative to the origin.
receipts is always an array, with 0 or more elements.

Device

{
   uuid: "75B538D8-67AF-44E8-86A0-B1A07BE137C8",
   name: "Anant's Mac Pro",
   type: "desktop",
   addedAt: "2012-02-28 12:23:35Z",
   apps: {}
}

apps is a TBD JSON blob that may indicate various screens of apps, and the order of apps within each screen. It may be fairly large.

An abbreviated device document is everything without the apps field, which could be quite large.

REST API

Authentication

Authentication uses [REST Auth].

POST /auth
{assertion}

returns a JSON object:

{
  id: "...",
  key: "...",
  endpoint: "https://node12.apps.services.mozilla.com/aitc/user/123"
}

id and key are the key identifier and key itself used for MAC Auth.
endpoint is the prefix for all subsequent API calls

NOTE: not yet sure if the /user/123 should be included in this endpoint, or just as part of the later API spec.

Apps

List Apps

GET {endpoint}/apps/

returns a JSON array of Apps, with format defined above.

An optional GET parameter, ?abbreviated=1 causes the return value to be a JSON array of manifest URLs only.

Add/Update App

PUT {endpoint}/apps/{appid}
{app_document}

NOTE: consider adding detection of stale version, e.g. if two receipts uploaded at same time.

Remove App

DELETE {endpoint}/apps/{appid}

Devices

List Devices

GET {endpoint}/devices/

returns a JSON array of abbreviated devices.

Single Device

GET {endpoint}/devices/{uuid}

returns a full device document

Add/Update Device

PUT {endpoint}/devices/{uuid}
{device_document}

Delete Device

DELETE {endpoint}/devices/{uuid}

Optimization

Listing of Apps and Devices can be qualified with a standard HTTP header:

If-Modified-Since: Tuesday, 28 Oct 2012 19:43:31 GMT

As per the HTTP spec, if the date does not properly parse, or if the list has been modified since that date, then the output is exactly as specified above already. However, if the list has not changed, then the server returns a 304 not-modified response with no body.