Field Masks

A field mask tells the EasyRoutes API which fields of a resource you want to update on a partial update (PATCH) request. Only the fields listed in the mask are written; all other fields on the resource are left unchanged.

Under the hood, EasyRoutes field masks are google.protobuf.FieldMask values exchanged as JSON.

Wire format

In JSON requests, a field mask is sent as a single string containing a comma-separated list of field paths.

{
  "updateMask": "note,tags"
}

Each path is a lowerCamelCase field name on the update payload for the request (for example, on the routeStop object for PATCH /routes/{routeId}/stops/{stopId}), not on the request envelope.

EasyRoutes' field masks are intentionally minimal — only the literal field names listed in the endpoint's update payload are accepted. The * wildcard, nested path prefixes, and dotted sub-field paths are not supported at this time.

Semantics

Mask contents	Result
Path is listed	The corresponding field on the payload replaces the current value on the resource.
Path is omitted	The current value on the resource is left unchanged, even if the payload sets it.
Path is unknown on the payload	The request fails with HTTP `400` — Bad Request
Mask is missing	The request fails with HTTP `400` — Bad Request
Mask is present but empty	The request fails with HTTP `400` — Bad Request

Tips:

To clear a field, list its path in the mask and send the empty/default value (e.g. "" for a string, [] for a list) in the payload.
For repeated fields, the supplied list replaces the existing list rather than appending to it.
Each endpoint enforces its own per-field validation (length limits, count limits, etc.) on the values you send for paths listed in the mask. See the endpoint reference for specifics.

Example: updating a stop

PATCH /routes/{routeId}/stops/{stopId} accepts a RouteStopUpdate payload plus an updateMask. To update only the note on a stop and leave its tags unchanged:

curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "routeStop": {
      "note": "Leave at the side door"
    },
    "updateMask": "note"
  }' \
  https://easyroutes.roundtrip.ai/api/2024-07/routes/rte-.../stops/rst-...

To replace the tags on the stop and clear its note in a single call:

curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "routeStop": {
      "note": "",
      "tags": ["fragile", "signature-required"]
    },
    "updateMask": "note,tags"
  }' \
  https://easyroutes.roundtrip.ai/api/2024-07/routes/rte-.../stops/rst-...

Wire format

Semantics

Example: updating a stop

On this page