Syncing and offline reading #

This page is for app developers whose app must work offline: a field guide, a catalog for sales staff, a manual on a ship. Exponential has no change feed for the whole tree, so the app syncs what it needs with the routes there are. The design below is a suggestion built on those routes.

Contents #

1. Choose what to sync
2. The first full sync
3. Incremental syncs
4. Removed items
5. Writes made offline

Choose what to sync #

Sync folders, not the site: one or a few subtrees the app shows, agreed with the site team by remote id (Node ids, remote ids and deep links). Decide which image alias to store per item, and leave originals out.

The first full sync #

For each synced folder:

1. Page through GET /api/ezp/v2/content/node/<id>/list/offset/<n>/limit/50?ResponseGroups=Fields until offset reaches metadata.childrenCount (Listing children and pagination).
2. For each child that is itself a container the app shows, repeat.
3. Fetch one alias URL per image (expimage::url) and download the files.
4. Store nodeId, dateModified and the answer; remember when the sync started.

Incremental syncs #

For changed items deeper in the tree, combine: modifiedSince for new items, and a modification-sorted list per synced folder for edits.

Removed items #

A removed item simply disappears from lists. Detect it by:

• a 404 when the app reads a detail it had cached, then delete it locally;
• a childrenCount lower than the number of local children, then re-read the folder's node ids (a list without Fields is light) and delete the ones that are gone.

Items hidden from the app's user, or moved out of the synced folder, look the same as removed ones from the app's side.

Writes made offline #

• Queue writes on the device with everything needed to send them later.
• Give each queued create a remote_id made on the device, and send it with expnode::create: if the connection drops after the server published it, the retry answers 409 instead of creating a duplicate (Writing through expservices).
• Send queued writes one at a time, in order, when the device is online; stop the queue on 401 and ask the user to sign in.
• Updates made offline can conflict with edits made on the site meanwhile. Compare the item's dateModified with the value the user saw before you send an update, and ask the user when they differ. The server publishes whatever is sent last.

Related pages #

• Caching in the app
• Caching on the server
• What the APIs do not do
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.