Skip to content

Nitrogen purge API

You can integrate purge API in your build script to purge the relevant/changed resource’s cache.

Note: For demo purpose, we will be using www.nviztest.com domain as an example.

Prerequisite

  1. You must have a domain configured on Nitrogen.
  2. You must have caching configured. If not, you can refer this article for the same.
  3. You must have a service account configured with Editor access. If not, you can refer this article for the same.

Steps

This involves 2 steps: getting the list of all purge-groups, and then configuring the purge API for the required one.

Step 1. Getting the list of all purge-groups:
Call the below API which will give you details about all the caching/purge groups you have configured currently:

Method:::
    GET
URL:::
    https://dash.n7.io/api/v2/nda/delivery/purge-v2/options?domain={domain-name}
Request headers:::
    Authorization: Token {api-key-of-service-account}

e.g.

curl \
-X GET "https://dash.n7.io/api/v2/nda/delivery/purge-v2/options?domain=www.nviztest.com" \
-H "Authorization: Token HVURnx6EnCEWfz8mfGtUwJ/7cYIJW/bBgLSLEteX"

Note:

  1. Please provide the correct domain name
  2. Please provide the correct service-token

If all the provided details are correct, you will get a response with below structure :

    {
        "domain": "www.nviztest.com",
        "items": [
            {
                "id": "OmZ1bGxzaXRlOjo6Ojo6",
                "name": "Full Site",
                "comment": ""
            },
            {
                "id": "OnVybDo6Ojo6Ojo6Ojo6",
                "name": "Purge Specific URLs",
                "comment": ""
            },
            {
                "id": "OnVybC1haW86Ojo6Ojo6",
                "name": "Purge Specific Image URLs",
                "comment": ""
            },
            {
                "id": "OmZ1bGxzaXRlLWFpbzo6",
                "name": "Homepage",
                "comment": ""
            },
            {
                "id": "OmY2bGxzaXRlLWFpbyn5",
                "name": "PLP",
                "comment": ""
            },
            {
                "id": "OmX3bGxzaXRlLWFpbxm4",
                "name": "PDP",
                "comment": ""
            },
            {
                "id": "OpZ2bGxzaXRlLXGpbzp7",
                "name": "Everything else",
                "comment": ""
            }
        ]
    }

Step 2. Configuring purge API for required purge-group:
As you can see, the response of above API has all the caching groups you have configured till now. And, each of these groups have an id associated with it.
Please copy the id of the purge group you need to configure the API for.

Note: Ideally, you can configure the API for Purge Specific URLs group as it gives you flexibility to purge any URL irrespective of purge-group.
Or you can configure purge for specific sections as well like PLP, PDP etc. to purge cache for all matching URLs together.
Please note that, Images can only be purged from Purge Specific Image URLs group. Purging images from any other group will have no effect.

Configure your purge API in below format by providing the required details:

Method:::
    POST
URL:::
    https://dash.n7.io/api/v2/nda/delivery/purge/requests
Request headers:::
    Authorization: Token {api-key-of-service-account}
Body:::
    {
        "domain": "{domain-name}",
        "purgeOptionId": "{purge-group-id}",
        "mediaPaths": [
            "{url-to-be-purged}"
        ]
    }

e.g.

curl \
-X POST "https://dash.n7.io/api/v2/nda/delivery/purge/requests" \
-H "Authorization: Token HVURnx6EnCEWfz8mfGtUwJ/7cYIJW/bBgLSLEteX" \
--data '{
        "domain": "www.nviztest.com",
        "purgeOptionId": "OnVybDo6Ojo6Ojo6Ojo6",
        "mediaPaths": [
            "https://www.nviztest.com/pages/contact-us.html",
            "https://www.nviztest.com/pages/about-us.html"
        ]
    }'

Notes:

  • mediaPaths attribute can only be given for Purge Specific URLs or Purge Specific Image URLs purge group which accepts URLs to be purged.

  • All other groups will purge all the URLs cached for that caching-group.

  • A valid purge request will receive below response with 200 status code, and will also be shown in Purge logs:

{
    "message": "Ok"
}
  • An invalid or rejected or failed purge request will receive below type of response with non-200 status code, and respective error details:
{
    "code": <error-id>,
    "message": "<error-message>",
    "details": [<error-detail1>, <error-detail2>, <error-detail3>],
    "rejectedMediaPaths": [<rejected-url>, <rejected-url2>, <rejected-url3>]
}

Notes

  1. You can only send 10 URLs per purge request.

  2. Please note that, Images can only be purged from Purge Specific Image URLs group. Purging images from other groups wil have no effect.

  3. Wildcard purge is not supported. You can create a Purge Group for respective URL pattern to purge them together.

  4. Purge may take up to 2-3 minutes max.

  5. In case you do not see the latest content even after 10 mins of purge, please raise a ticket with the URL and screenshot of the expected change. But, before that, please ensure that your servers are sending the latest content.

  6. Refer Nitrogen response header to understand cache status of any resource.

  7. Any caching group when configured, may take up-to 5 minutes to be available in purge screen and purge API.