Sandboxes

Sandboxes are a way of storing problem files on the RouteCloud API server. Sandboxes provide a way for users to visualize the data as it can be viewed and edited in the UI.

Endpoints

List

A list of existing sandboxes can be retrieved using GET /v1/sandboxes.

Create

Create a sandbox by POSTing a problem file to /v1/sandboxes?name={sandbox_name}. The sandbox must be given a unique name. This creates a sandbox with one revision - a snapshot revision of its initial problem. See Create Sandbox.

Rename

Rename a sandbox by POSTing a new sandbox name to /v1/sandboxes/{sandbox_id}/rename?name={sandbox_name}.

Update

Update the sandbox by POSTing a new problem to /v1/sandboxes/{sandbox_id}. This appends a new snapshot revision to the sandbox.

Retrieve

The state of the sandbox at any revision can be retrieved using GET /v1/sandboxes/{sandbox_id}.

Expiry

Set sandbox expiry interval by POSTing a new interval value to /v1/sandboxes/{sandbox_id}/expiry?interval={interval}.

Update Incrementally

A revision can be added to a sandbox by POSTing to /v1/sandboxes/{sandbox_id}/revisions. The delta is used to incrementally update the existing sandbox problem file data.

Retrieve Revisions

API clients can long-poll for new revisions to a sandbox, enabling them to stay synchronized with the sandbox in real-time. A client can long-poll for revisions by calling GET /v1/sandboxes/{sandbox_id}/revisions?from={revision_number}&wait=1. Any revisions starting from revision_number are returned. The server waits up to 15 seconds for any new revisions to be created, returning immediately as soon as a revision becomes available.

Canonical Form

The RouteCloud API can accept problem files in different forms, but it always stores sandbox problem files in canonical form. Canonical form allows API clients to revise all problem files in a consistent way. Canonical form does not store calculated values, avoiding the possibility for data to become inconsistent. Whenever a sandbox snapshot is created, that snapshot is always converted to canonical form.

Canonical form:

• All entities, except for marker, must be stored on the problem top-level collection and must not be stored inline. Marker can be either inline or referenced. See Referencing vs Inlining.
• route.stops cannot be used since the position of depots, breaks, and overnights is a calculated value. route.jobs may be used instead.

{
  "routes": [
	"id": "route0"
    "driver": { "id": "driver0" },
    "jobs": [
      {
        "id": "job0",
        "location": { "lat": -43.21, "lon": 172.1 }
      }
    ]
  ]
}

Example of a non-canonical problem file.

This problem is not canonical because:

• route.driver is defined inline and not referenced on problem.drivers.
• route.jobs contains an inline job that should be on problem.jobs.

{
  "routes": [
    {
      "id": "route0",
	  "driver": "driver0",
      "jobs": [ "job0" ],
    }
  ],
  "jobs": [
    {
      "id": "job0",
      "location": { "lat": -43.21, "lon": 172.1 }
    }
  ],
  "drivers": [
    { "id": "driver0" }
  ]
}

The same problem file in canonical form.

When a sandbox is retrieved, it is always in canonical form.

Revisions

API clients can read and write sandbox revisions to a sandbox. The enables multiple API clients to interact with a sandbox simultaneously while guaranteeing data consistency.

A revision can be one of three types:

• Snapshots - replace the data in the sandbox with a new JSON problem blob. See revision.snapshot.
• Deltas - incrementally modify the data in the sandbox. See revision.delta.
• Undo/Redo - revert the sandbox to a previously-created revision. See revision.undo_redo_to_revision.

Revision numbers

All revisions in a sandbox are assigned a unique sequential number, with the first revision in the sandbox always being revision 0. The latest_revision number is always incremented with every new revision. An undo/redo revision restores the sandbox to a previous state, and can cause the active_revision to revert to an old revision number.

If an undo/redo revision restores a previous state, then subsequently a new snapshot or delta revision is added to the sandbox, and the revision history is replaced from that point forward. For example:

• Initial revision sequence:
  • Revision 0: Snapshot
  • Revision 1: Delta
  • Revision 2: Delta
  • Revision 3: Delta
  • Current sandbox state: latest_revision=3, active_revision=3
• Undo/redo revision added, restoring revision number 2. New revision sequence:
  • Revision 0: Snapshot
  • Revision 1: Delta
  • Revision 2: Delta
  • Revision 3: Delta
  • Revision 4: Undo/Redo to revision number 2 (new)
  • Current sandbox state: latest_revision=4, active_revision=2
• Delta revision committed. New revision sequence:
  • Revision 0: Snapshot
  • Revision 1: Delta
  • Revision 2: Delta
  • (Revision 3 deleted)
  • (Revision 4 deleted)
  • Revision 5: Delta (new)
  • Current sandbox state: latest_revision=5, active_revision=5

Note that when the delta revision was committed after an undo, all existing revisions after active_revision were deleted as they are no longer part of the current revision history.

Deltas

Deltas incrementally modify the data in the sandbox. As deltas describe only the changes, they are normally more efficient than replacing the entire contents of the sandbox. The UI is designed to work well with deltas. If an API client creates a delta while a user has the sandbox open in the UI, the UI applies the deltas in real-time while the user has the sandbox open.

Retention policy

Historical revisions of a problem file are stored for up to seven days.

Tags

When a revision is created, the client may specify a tag. This tag may help clients identify the revision later. The tag is treated by the server as an opaque string and can be any string.

Permissions

By default, sandboxes can be accessed only by their owner and the subuser who created them. If other subusers need to access the same sandbox the owner may grant them permission using these APIs.

See Also

• API Overview