Using Umbraco's Content Delivery API

Developer hints and tips for working with Umbraco's content delivery API. Configuring the API, and using Postman to interact with it

With versions 12 and 13, Umbarco have introduced a Content Delivery API. These API features introduce first-classsupport for modern front end frameworks. Umbraco's documentation currently covers the V12 version of the Delivery API. Umbraco version 13 introduced a new second API definition. 

Some hints and tips to get started are outlined below. 

1. Enabling the Umbraco Delivery API

In Umbraco V13, Delivery Api is configured by default, but disabled via your site's `appsettings.json` config file.   

  • In `appsettings.json`, set Umbraco -> CMS -> DeliveryApi -> Enabled: true
  • Restart the site
  • Navigate to {your_site_url}/umbraco/swagger/index.html?urls.primaryName=Umbraco%20Delivery%20API to view your site's swagger document

The swagger endpoint will only open in non-production environments. To test against a production instance, navigate to {your_site_url}/umbraco/delivery/api/v2/content/item/:path.

    "Umbraco": {
  "CMS": {
    "DeliveryApi": {
      "Enabled": true,    // enables the DeliveryApi
    },
 }
}

Fig 1: appsettings.json to enable the delivery API

The Api is now publicly available. This may not be what you intend. Restricting access is covered in the next section.

2. Restrict Access by Api Key

Limit access to your Umbraco Delivery Api with an API Key:

  • Open your `appsettings.json` file
  • Update the `DeliveryApi` node to include `PublicAccess: false` and `ApiKey: "YOUR_API_KEY_HERE"`

Visiting /umbraco/delivery/api/v2/content/item/:path should now return a `401: Unauthorized` error. 

      "Umbraco": {
    "CMS": {
      "DeliveryApi": {
        "Enabled": true,    // enables the DeliveryApi
        "PublicAccess": false,   // Restricts access by ApiKey
        "ApiKey": "YOUR_API_KEY_HERE",     // The required ApiKey 
      },
   }
}

appsettings.json to restrict the delivery API's public access

3. Importing Umbraco Delivery API into Postman

The Umbraco Delivery API uses an OpenAPI definition. In development mode, you can view a human-readable version of this at /umbraco/swagger/index.html?urls.primaryName=Umbraco%20Delivery%20API . A machine-readable version, useful for importing to Postman, is available at /umbraco/swagger/delivery/swagger.json.  To import the definition to Postman:

  1. At the top of the left-hand menu, select Import (see fig 3.1)
  2. Paste the URL /umbraco/swagger/delivery/swagger.json
  3. Wait for Postman to read your collection
  4. From the popout window, select Postman Collection
  5. Select Collections in the left-hand menu, then select the newly imported collection Umbraco Delivery API

The imported collection includes both V1 and V2 of the API. V1 is obsolete, so unless you're specifically using that API, delete it form Postman to avoid confusion. 

Fig 3.1 - Importing an API collection into Postman

Fig 3.1 - Importing an API collection into Postman (click to open)

4. Add your ApiKey to all postman requests

Manually adding the Api Key header to each request is cumbersome. Postman offers a collection-wide Authorization editor to make this less of a pain. 

  1. Select your imported collection in postman
  2. Click Authorization from the horizontal collection menu
  3. Select Type
  4. Select API Key
  5. In the Key section, enter `Api-Key`
  6. In the Value enter `YOUR_API_KEY_HERE`
  7. In the select menu Add to, select Header
  8. Press `ctrl+s` to save the collection
Fig 4.1: How to configure your Umbraco Content Delivery API Key with Postman Authorization

Fig 4.1: How to configure your Umbraco Content Delivery API Key with Postman Authorization (click to open)

5. Add default settings to all postman requests

Umbraco's Delivery API allows you to customise your requests to include special Umbraco features. For example, in a multi-site environment, restricting your request to a Start-Item. Similarly, you can toggle Preview mode on and off. 

In Postman, these can be configured across the entire collection, using Pre-Request Scripts.

  1. From the left hand menu, select your collection
  2. Select the top Umbraco Delivery API folder
  3. From the horizontal menu, select Pre-request Script
  4. To configure a start node, enter `pm.request.headers.upsert({key: 'Start-Item', value: '01c100e1-5b5a-4e86-b23a-3c401390860f' })`
    1. This will restrict all Delivery API content requests to a descendants of the specific node (01c100e1-5b5a-4e86-b23a-3c401390860f in my case)
  5. To configure Preview Mode for all requests, `pm.request.headers.upsert({key: 'Preview', value: 'true' })`
    1. This will configure Delivery Api requests made from Postman to use Preview mode
    2. Disable preview mode by setting `value: 'false'`
  6. Press `ctrl+s` to save the pre-request settings
Fig 5.1 - How to configure your Postman collection's authorization, so that it automatically adds the Umbraco Content Delivery API Key to requests

Fig 5.1 - How to configure your Postman collection's authorization, so that it automatically adds the Umbraco Content Delivery API Key to requests (click to open) 

    pm.request.headers.upsert({key: 'Start-Item', value: '01c100e1-5b5a-4e86-b23a-3c401390860f' })
pm.request.headers.upsert({key: 'Preview', value: 'true' })

Configure preview mode and a content start node

You should now be set up to use the Umbraco Delivery Api in Postman.