Working with Edge Dictionary items using the API
Last updated January 18, 2019
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
WARNING: Dictionary item deletions are permanent. Fastly does not store data. If you delete a dictionary item, the entry is gone forever from all versions of your service.
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.
IMPORTANT: Personal information, secrets, or sensitive data should not be included in dictionaries or incorporated into VCL. In addition, we do not maintain version histories of your dictionaries. Our Compliance and Law FAQ describes in detail how Fastly handles personal data privacy.