View source for 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 [[../Sync/Spec|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",
    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 <tt>appid</tt>:

 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 <tt>uuid</tt>, 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 [https://wiki.mozilla.org/Identity/BrowserIDSync#BrowserID_.2B_REST 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 (<code>{apps: [{origin: "http://app1", modifiedAt: 1234}, ...]}</code>)

 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 <code>after=0</code> or no <code>after</code> argument to get all apps.

==== Add/Update App ====

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

Optionally, the header <code>X-If-Unmodified-Since</code>, 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.

== User Interface Considerations ==

== Implementation Notes ==