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.

Old and crufty. Go here instead: http://docs.services.mozilla.com/aitc/index.html

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",
   manifestPath: "/manifest.webapp",
   installOrigin: "https://marketplace.mozilla.org",
   installedAt: 1330535996745,
   modifiedAt: 1330535996945,
   receipts: ["...", "..."]
}

• manifestPath is where the manifest was found (relative to the origin)
• receipts is always an array, with 0 or more elements.
• installedAt and modificationAt are millisecond timestamps and are set by the server when an app document is stored.

An App is later identified by its appid:

appid = b64urlencode(SHA1(origin))

with no b64 padding.

An Abbreviated App document contains only the origin and modification time:

{
  origin: "https://example.com",
  modifiedAt: 1330535996945
}

Device

{
   uuid: "75B538D8-67AF-44E8-86A0-B1A07BE137C8",
   name: "Anant's Mac Pro",
   type: "mobile",
   layout: "android/phone",
   addedAt: 1330535996745,
   modifiedAt: 1330535999745,
   apps: {}
}

• apps is a JSON blob that may indicate various screens of apps, and the order of apps within each screen. It may be fairly large. The apps object can only really be understood relative to the layout: it will contain information about applications and how they are arranged, and how that arrangement looks and what structure it has is layout-dependent (for instance, Android has multiple screens, with icons laid out on those screens; another device may have a single desktop but with arbitrary pixel-based placement, and so on).

A Device is later identified by its uuid, a client-assigned value represented in uppercase hexadecimal notation.

An abbreviated device document is everything without the apps field, which could be quite large. This is sufficient for cases when you want to simply select a device (which requires at least name and uuid, and type might also be useful for some selectors).

Arrays

We never actually return JSON arrays (security problem on older browsers, and difficult to extend).

Instead, we return a JSON object with a top-level key whose value is the array in question. Specifically:

{apps: [..]}

or

{devices: [..]}

REST API

Authentication

Authentication uses BrowserID 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

Apps

List Apps

GET {endpoint}/apps/

returns a JSON array of Abbreviated Apps, with format defined above ({apps: [{origin: "http://app1", modifiedAt: 1234}, ...]})

GET {endpoint}/apps/?full=1&after={timestamp}

Returns:

{
  apps: [apps added or updated since after]
}

The value of the X-Timestamp header should be used for the next value of after. You may use after=0 or no after argument to get all apps.

Add/Update App

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

Optionally, the header X-If-Unmodified-Since, a millisecond timestamp, can be used to prevent conflicting updates. If there's a conflict, a 412 error is returned. If the app record does not exist, any value of this header will succeed, including 0.

This could do basic validation of the app document.

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}

server ensures that the UUID is properly formed.

Delete Device

DELETE {endpoint}/devices/{uuid}

Optimization

Listing of Apps and Devices can be qualified with the header:

X-If-Modified-Since: 

which behaves like the standard HTTP If-Modified-Since, only with a millisecond timestamp.