LOG IN SIGN UP
Documentation

Creating and manipulating dictionary items

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 geoIP redirects, the table would appear similar to this:

table geoip_redirect {
  "GB"  :  "www.example.co.uk",
  "IE"  :  "www.example.co.uk",
  "IT"  :  "www.example.com.it",
  "AU"  :  "www.example.com.au",
}

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

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

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

which would return this response:

{
  "version": <version_number>,
  "name": "geoip_redirect",
  "id": "<dictionary_id>",
  "service_id": "<service_id>"
}

Adding new items to dictionary

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

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

returns this response:

{
  "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:

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",
}

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 geoIP table to update an existing dictionary item or create it if it doesn't exist:

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

returns this response:

{
  "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:

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

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

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

returns this response:

{
  "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:

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:

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

{
  "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"
    }
  ]
}

Now you can make the following API call:

curl -X PATCH -H 'Content-Type: application/json' -H 'Fastly-Key: <API_key>' -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:

curl -X DELETE -H 'Fastly-Key: <API_key>' 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.


Back to Top