Fastly Dictionary API

openapi: 3.2.0
info:
  title: Fastly Edge Dictionaries Dictionary API
  description: The Fastly Edge Dictionaries API provides endpoints for creating and managing key-value lookup tables that are accessible at the edge without requiring a service version change. Dictionaries can store configuration data, feature flags, redirect mappings, and other dynamic values that VCL or Compute services can reference during request processing. The API supports CRUD operations on both dictionary containers and their individual items, as well as bulk updates for efficient management of large datasets.
  version: '1.0'
  contact:
    name: Fastly Support
    url: https://support.fastly.com
  termsOfService: https://www.fastly.com/terms
servers:
- url: https://api.fastly.com
  description: Fastly API Production Server
security:
- apiKeyAuth: []
tags:
- name: Dictionary
  description: Operations for managing dictionary containers within a service version.
paths:
  /service/{service_id}/version/{version_id}/dictionary:
    get:
      operationId: listDictionaries
      summary: List dictionaries
      description: Retrieves a list of all dictionaries configured for a specific version of a Fastly service.
      tags:
      - Dictionary
      parameters:
      - $ref: '#/components/parameters/serviceId'
      - $ref: '#/components/parameters/versionId'
      responses:
        '200':
          description: Successfully retrieved the list of dictionaries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dictionary'
        '401':
          description: Unauthorized. The API token is missing or invalid.
    post:
      operationId: createDictionary
      summary: Create a dictionary
      description: Creates a new dictionary container for a specific version of a Fastly service. Once the service version is activated, items within the dictionary become versionless and can be updated without requiring a new service version.
      tags:
      - Dictionary
      parameters:
      - $ref: '#/components/parameters/serviceId'
      - $ref: '#/components/parameters/versionId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the dictionary.
                write_only:
                  type: boolean
                  description: Whether the dictionary is write-only, meaning items can only be set or deleted but not read.
      responses:
        '200':
          description: Successfully created the dictionary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dictionary'
        '400':
          description: Bad request. Missing or invalid parameters.
        '401':
          description: Unauthorized. The API token is missing or invalid.
  /service/{service_id}/version/{version_id}/dictionary/{dictionary_name}:
    get:
      operationId: getDictionary
      summary: Get a dictionary
      description: Retrieves the details of a specific dictionary container for a version of a Fastly service.
      tags:
      - Dictionary
      parameters:
      - $ref: '#/components/parameters/serviceId'
      - $ref: '#/components/parameters/versionId'
      - name: dictionary_name
        in: path
        required: true
        description: The name of the dictionary.
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved the dictionary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dictionary'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Dictionary not found.
    put:
      operationId: updateDictionary
      summary: Update a dictionary
      description: Updates a specific dictionary container for a version of a Fastly service.
      tags:
      - Dictionary
      parameters:
      - $ref: '#/components/parameters/serviceId'
      - $ref: '#/components/parameters/versionId'
      - name: dictionary_name
        in: path
        required: true
        description: The name of the dictionary.
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The new name of the dictionary.
                write_only:
                  type: boolean
                  description: Whether the dictionary is write-only.
      responses:
        '200':
          description: Successfully updated the dictionary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dictionary'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Dictionary not found.
    delete:
      operationId: deleteDictionary
      summary: Delete a dictionary
      description: Deletes a specific dictionary container from a version of a Fastly service.
      tags:
      - Dictionary
      parameters:
      - $ref: '#/components/parameters/serviceId'
      - $ref: '#/components/parameters/versionId'
      - name: dictionary_name
        in: path
        required: true
        description: The name of the dictionary.
        schema:
          type: string
      responses:
        '200':
          description: Successfully deleted the dictionary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Confirmation status of the deletion.
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Dictionary not found.
components:
  parameters:
    serviceId:
      name: service_id
      in: path
      required: true
      description: The alphanumeric string identifying the Fastly service.
      schema:
        type: string
    versionId:
      name: version_id
      in: path
      required: true
      description: The integer identifying the service version.
      schema:
        type: integer
  schemas:
    Dictionary:
      type: object
      description: A dictionary container that holds key-value pairs accessible at the Fastly edge for use in VCL or Compute services.
      properties:
        id:
          type: string
          description: The alphanumeric string identifying the dictionary.
        name:
          type: string
          description: The name of the dictionary.
        service_id:
          type: string
          description: The alphanumeric string identifying the service.
        version:
          type: integer
          description: The version number the dictionary is associated with.
        write_only:
          type: boolean
          description: Whether the dictionary is write-only.
        created_at:
          type: string
          format: date-time
          description: The date and time the dictionary was created.
        updated_at:
          type: string
          format: date-time
          description: The date and time the dictionary was last updated.
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: The date and time the dictionary was deleted.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Fastly-Key
      description: API token used to authenticate requests to the Fastly API.
externalDocs:
  description: Fastly Edge Dictionaries API Documentation
  url: https://www.fastly.com/documentation/reference/api/dictionaries/