REST API: Mutation and Conflict Resolution

When dealing with real-time updates, some Twilio API resources utilize the If-Match and ETag HTTP headers for conditional mutation. Every response containing these objects will return an ETag value, which you can compare against an If-Match header.

The following resources currently support this form of conflict resolution:

Let's walk through a workflow using the Task resource:

Create and Update a Resource

We often make requests with the idea of "optimistic concurrency". For example, let's say that you request to create a Task, like so:

Create a Task

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createTask() {
11  const task = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .tasks.create({ attributes: JSON.stringify({ foo: "bar" }) });
14
15  console.log(task.accountSid);
16}
17
18createTask();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "age": 25200,
4  "assignment_status": "pending",
5  "attributes": "{\"foo\": \"bar\"}",
6  "date_created": "2014-05-14T18:50:02Z",
7  "date_updated": "2014-05-15T07:26:06Z",
8  "task_queue_entered_date": null,
9  "virtual_start_time": "2014-05-14T18:50:02Z",
10  "priority": 1,
11  "reason": "Test Reason",
12  "sid": "WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "task_queue_sid": "WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14  "task_channel_sid": "TCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "task_channel_unique_name": "unique",
16  "timeout": 60,
17  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Tasks/WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
19  "workflow_sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
20  "workflow_friendly_name": "Example Workflow",
21  "task_queue_friendly_name": "Example Task Queue",
22  "ignore_capacity": false,
23  "routing_target": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
24  "addons": "{}",
25  "links": {
26    "task_queue": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TaskQueues/WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
27    "workflow": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
28    "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
29    "reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Tasks/WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Reservations"
30  }
31}

This will create a Task with the attributes {"foo": "bar"}. Now you can update that object through the REST API.

POST A: Update Task attributes to bar-SFO

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateTask() {
11  const task = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .tasks("WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .update({ attributes: JSON.stringify({ foo: "bar-SFO" }) });
15
16  console.log(task.accountSid);
17}
18
19updateTask();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "age": 25200,
4  "assignment_status": "pending",
5  "attributes": "{\"foo\": \"bar-SFO\"}",
6  "date_created": "2014-05-14T18:50:02Z",
7  "date_updated": "2014-05-15T07:26:06Z",
8  "task_queue_entered_date": "2014-05-14T18:50:02Z",
9  "virtual_start_time": "2023-08-02T12:34:56Z",
10  "priority": 0,
11  "reason": "Test Reason",
12  "sid": "WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "task_queue_sid": "WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14  "task_channel_sid": "TCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "task_channel_unique_name": "task-channel",
16  "timeout": 60,
17  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Tasks/WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "workflow_sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
19  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
20  "workflow_friendly_name": "Test Workflow",
21  "task_queue_friendly_name": "Test Queue",
22  "addons": "{}",
23  "ignore_capacity": false,
24  "routing_target": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25  "links": {
26    "task_queue": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TaskQueues/WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
27    "workflow": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
28    "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
29    "reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Tasks/WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Reservations"
30  }
31}

You'll get a response back, and the attributes will now be {"foo": "bar-SFO"}. This is optimistic concurrency - you assume that you are the only person making changes to the Task, so foo used to be bar, and now it's bar-SFO.

This might work a lot of the time, but let's say there is an argument over whether the attribute should be bar-SFO or bar-DEN. Now you have two POST requests trying to update the Task in quick succession: POST A (the same request as above) and POST B.

What will happen in this condition?

Post B: Update Attributes to bar-DEN

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateTask() {
11  const task = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .tasks("WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .update({ attributes: JSON.stringify({ foo: "bar-DEN" }) });
15
16  console.log(task.accountSid);
17}
18
19updateTask();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "age": 25200,
4  "assignment_status": "pending",
5  "attributes": "{\"foo\": \"bar-DEN\"}",
6  "date_created": "2014-05-14T18:50:02Z",
7  "date_updated": "2014-05-15T07:26:06Z",
8  "task_queue_entered_date": "2014-05-14T18:50:02Z",
9  "virtual_start_time": "2023-08-02T12:34:56Z",
10  "priority": 0,
11  "reason": "Test Reason",
12  "sid": "WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "task_queue_sid": "WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14  "task_channel_sid": "TCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "task_channel_unique_name": "task-channel",
16  "timeout": 60,
17  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Tasks/WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "workflow_sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
19  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
20  "workflow_friendly_name": "Test Workflow",
21  "task_queue_friendly_name": "Test Queue",
22  "addons": "{}",
23  "ignore_capacity": false,
24  "routing_target": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25  "links": {
26    "task_queue": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TaskQueues/WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
27    "workflow": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
28    "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
29    "reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Tasks/WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Reservations"
30  }
31}

Resolve Multiple Updates to a Resource

The last writer wins. Because we're operating on the model of optimistic concurrency, POST B will simply overwrite POST A.

Fortunately, you can avoid these race conditions. You'll notice that the attributes aren't the only thing that changed when you updated your resource: Your ETag header will have incremented from 0 to 1 in the response.

Now, you can use the If-Match header to check that the version of the Resource is up-to-date before sending your update through. First, GET the Task to retrieve the ETag header. Then pass this revision as a value in the If-Match header when you post your update. This ensures that, if you are not referencing the most up-to-date revision, the update will be rejected.

Update with If-Match Header

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateTask() {
11  const task = await client.taskrouter.v1
12    .workspaces("WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .tasks("WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .update({
15      attributes: JSON.stringify({ foo: "bar-DEN" }),
16      ifMatch: "0",
17    });
18
19  console.log(task.accountSid);
20}
21
22updateTask();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "age": 25200,
4  "assignment_status": "pending",
5  "attributes": "{\"foo\": \"bar-DEN\"}",
6  "date_created": "2014-05-14T18:50:02Z",
7  "date_updated": "2014-05-15T07:26:06Z",
8  "task_queue_entered_date": "2014-05-14T18:50:02Z",
9  "virtual_start_time": "2023-08-02T12:34:56Z",
10  "priority": 0,
11  "reason": "Test Reason",
12  "sid": "WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "task_queue_sid": "WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14  "task_channel_sid": "TCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15  "task_channel_unique_name": "task-channel",
16  "timeout": 60,
17  "url": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Tasks/WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "workflow_sid": "WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
19  "workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
20  "workflow_friendly_name": "Test Workflow",
21  "task_queue_friendly_name": "Test Queue",
22  "addons": "{}",
23  "ignore_capacity": false,
24  "routing_target": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
25  "links": {
26    "task_queue": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/TaskQueues/WQaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
27    "workflow": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Workflows/WWaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
28    "workspace": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
29    "reservations": "https://taskrouter.twilio.com/v1/Workspaces/WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Tasks/WTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Reservations"
30  }
31}

Note the addition of the If-Match header. Now, this operation will fail with a 412 Response because the submitted ETag value is 0 and the current Attributes are different.

When you're testing or building a simple application, this might not be a critical step. If, however, your resource can be mutated by multiple sources at a time, using these headers will help ensure that you don't accidentally overwrite and/or lose any updates.

Next Steps

Start making your own requests to the Twilio API
Secure your app with the Twilio HTTP header, X-TWILIO-SIGNATURE
Learn more about what to expect in Twilio's HTTP Response