Working with Edge Dictionary items using the API

A dictionary item is a key-value pair that makes up an entry in a dictionary container in an Edge Dictionary. Once you create an Edge Dictionary and associate the dictionary container with a service, any dictionary items created will appear in your generated VCL.

For example, if you were using Edge Dictionaries to control geolocation redirects, the table would appear similar to this:

1
2
3
4
5
6
table geoip_redirect {
  "GB"  :  "www.example.co.uk",
  "IE"  :  "www.example.co.uk",
  "IT"  :  "www.example.com.it",
  "AU"  :  "www.example.com.au",
}

Finding a dictionary container's ID

If you already have a dictionary container associated with an active version of your service, you can add, update, or delete the items in it as long as you know the dictionary_id.

In our geolocation example, you would find your dictionary_id using the following API call:

1
2
curl -H 'Fastly-Key: FASTLY_API_TOKEN'
https://api.fastly.com/service/<service_id>/version/<version_number>/dictionary/geoip_redirect

which would return this response:

1
2
3
4
5
6
{
  "version": <version_number>,
  "name": "geoip_redirect",
  "id": "<dictionary_id>",
  "service_id": "<service_id>"
}

Adding new items to a dictionary

You can add new dictionary items without having to increment your service version number. For example, this API call to a geolocation table to add a new dictionary item:

1
curl -X POST -H 'Fastly-Key: FASTLY_API_TOKEN' -d 'item_key=NZ&item_value=www.example.com.au' "https://api.fastly.com/service/<service_id>/dictionary/<dictionary_id>/item"

returns this response:

1
2
3
4
5
6
{
  "dictionary_id": "<dictionary_id>",
  "service_id": "<service_id>",
  "item_key": "NZ",
  "item_value": "www.example.com.au"
}

The table in the generated VCL would then be updated with the new dictionary item and look like this:

1
2
3
4
5
6
7
table geoip_redirect {
  "GB"  :  "www.example.co.uk",
  "IE"  :  "www.example.co.uk",
  "IT"  :  "www.example.com.it",
  "AU"  :  "www.example.com.au",
  "NZ"  :  "www.example.com.au",
}

Listing dictionary items

You can view all of the dictionary items in an Edge Dictionary. For example, this API call:

1
curl -H "Fastly-Key: FASTLY_API_TOKEN" https://api.fastly.com/service/<service_id>/dictionary/<dictionary_id>/items

returns this response:

1
2
3
4
5
6
7
8
9
{
  "dictionary_id": "<dictionary_id>",
  "service_id": "<service_id>",
  "item_key": "some_key",
  "item_value": "some_value",
  "created_at": "2016-04-21T18:14:32+00:00",
  "deleted_at": null,
  "updated_at": "2016-04-21T18:14:32+00:00"
}

Upserting dictionary items

You can create and update dictionary items regardless of whether or not they exist. For example, the following API call to the geolocation table to update an existing dictionary item or create it if it doesn't exist:

1
curl -X PUT -H 'Fastly-Key: FASTLY_API_TOKEN' -d 'item_value=www.example.co.aq' "https://api.fastly.com/service/<service_id>/dictionary/<dictionary_id>/item/AQ"

returns this response:

1
2
3
4
5
6
{
  "dictionary_id": "<dictionary_id>",
  "item_key": "AQ",
  "item_value": "www.example.co.aq",
  "service_id": "<service_id>"
}

The table in the generated VCL would then be updated with the new dictionary item and look like this:

1
2
3
4
5
6
7
8
table geoip_redirect {
  "GB"  :  "www.example.co.uk",
  "IE"  :  "www.example.co.uk",
  "IT"  :  "www.example.com.it",
  "AU"  :  "www.example.com.au",
  "NZ"  :  "www.example.com.au",
  "AQ"  :  "www.example.co.aq",
}

Updating dictionary items one at a time

You can also update any dictionary item without having to increment your service version number. For example, the following API call to the geolocation table to update an existing dictionary item:

1
curl -X PATCH -H 'Fastly-Key: FASTLY_API_TOKEN' -d 'item_value=www.example.co.uk' "https://api.fastly.com/service/<service_id>/dictionary/<dictionary_id>/item/NZ"

returns this response:

1
2
3
4
5
6
{
  "dictionary_id": "<dictionary_id>",
  "item_key": "NZ",
  "item_value": "www.example.co.uk",
  "service_id": "<service_id>"
}

The table in the generated VCL would then be updated with the new dictionary item and look like this:

1
2
3
4
5
6
7
8
table geoip_redirect {
  "GB"  :  "www.example.co.uk",
  "IE"  :  "www.example.co.uk",
  "IT"  :  "www.example.com.it",
  "AU"  :  "www.example.com.au",
  "NZ"  :  "www.example.co.uk",
  "AQ"  :  "www.example.co.aq",
}

Batch updating dictionary items

You can update up to 1,000 dictionary items with a single API call. The following actions are available within a batch update:

• Upsert - Creates an item if it doesn't exist, otherwise modifies the existing one.
• Create - Creates a new item, but will not update an existing one.
• Update - Updates an existing item, but will not create a new one if it doesn't exist.
• Delete - Permanently deletes the item from the dictionary.

For example, to batch update existing dictionary items in the geolocation table, create a new file called batch.json that contains the following JSON-encoded data:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "items": [
    {
      "op": "create",
      "item_key": "JP",
      "item_value": "www.example.co.jp"
    },
    {
      "op": "update",
      "item_key": "GB",
      "item_value": "www.example.co.uk"
    },
    {
      "op": "delete",
      "item_key": "IT"
    }
  ]
}

Then you can make the following API call:

1
curl -X PATCH -H 'Content-Type: application/json' -H 'Fastly-Key: FASTLY_API_TOKEN' -d @batch.json "https://api.fastly.com/service/<service_id>/dictionary/<dictionary_id>/items"

See the API documentation for more information.

Deleting a dictionary item

To remove an item from your table, use this API call:

1
curl -X DELETE -H 'Fastly-Key: FASTLY_API_TOKEN' https://api.fastly.com/service/<service_id>/dictionary/<dictionary_id>/item/NZ

Unlike creation and update of dictionary items, the API call returns no response.