ESI Debugger API v1

Troubleshoot, review, and debug your website’s ESI code.

Learn more:


Overview

ESI Debugger API helps you troubleshoot, review, and debug your Edge Side Includes (ESI) code. By providing a URL to your website or to your test server, you can generate a comprehensive debugging report. You can receive information about any ESI syntax errors, evaluation messages to check whether the site is working properly, and all environment variables used for your test. Also, it provides features that let you emulate user geographical data and client-browser conditions.

ESI is an XML-based markup language that provides a way to assemble resources in HTTP clients. ESI leverages client tools such as caches to improve end-user performance, reduce processing overhead on the origin server, and enhance availability. It allows for dynamic content assembly at the edge of the network, whether it is in a content delivery network, end-user’s browser, or a reverse proxy right next to the origin server.

Who should use this API

Use this API as part of an automated system to debug, test, and view websites containing ESI code. You can use it to debug production websites or test origin sites. For testing purposes, you can set up a test origin server to debug websites before deployment or modification. This API also lets you specify client request headers to emulate browsers and client IP addresses to emulate content targeting EdgeScape GEO data.

Getting started

To configure this API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named Diagnostic Tools, and set the access level to READ-WRITE.

  • To diagnose many common problems Akamai customers experience when delivering content to their end users, see also The Diagnostic Tools API.

Resources

This API provides an ESI debugging report.

  • ESI debugging report. A debugging report on the ESI code of a source page and all included pages.

An ESI debugging report consists of the following subsections:

  • Enumerated source. Shows the ESI source code.

  • Environment variables. Reports all ESI-supported environment variables and their values.

  • Syntax messages. Reports ESI syntax errors.

  • Evaluation messages. Reports information, warning, and error messages about ESI processing.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Get an ESI debugging report POST /diagnostic-tools/v2/esi-debugger-api/v1/debug

Get an ESI debugging report

This operation provides a debugging report on the ESI code of your source page and all pages that the source page references.

POST /diagnostic-tools/v2/esi-debugger-api/v1/debug

Content-Type: application/json

Request Body:

{
    "url": "https://www.abc.com",
    "clientRequestHeaders": {
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8;"
    },
    "clientIP": "192.168.76.67",
    "originServer": "test.server"
}

Status 200 application/json

Response Body:

{
    "sourceDebugPage": {
        "pageLink": "http://www.abc.com/",
        "enumeratedSource": [
            "//1    ",
            "//2    <!DOCTYPE html><html class=\"no-js\">",
            "//3    <head>",
            "//4    <meta charset=\"utf-8\">",
            "//5   <esi:choose>",
            "//6   <esi:when test=\"$len($(HTTP_HOST{0}))>1\">",
            "//21   <esi:assign name=\"currenthost\" value=\"$(HTTP_HOST{0})\"/>",
            "//22   </esi:when>",
            "//23   <esi:otherwise>",
            "//24   <esi:assign name=\"currenthost\" value=\"$(HTTP_HOST)\"/>",
            "//25   </esi:otherwise>",
            "//26   </esi:choose>",
            "//27   <esi:choose>",
            "//28   <esi:when test=\"$substr( $(currenthost), 0, $index($(currenthost), '.')) == inactive\">",
            "//29   <esi:assign name=\"versionPath\" value=\"inactiveversion\"/>",
            "//30   </esi:when>",
            "//31   <esi:when test=\"$substr( $(currenthost), 0, $index($(currenthost), '.')) == deploy\">",
            "//32   <esi:assign name=\"versionPath\" value=\"inactiveversion\"/>",
            "//33   </esi:when>",
            "//34   <esi:otherwise>",
            "//35   <esi:assign name=\"versionPath\" value=\"version\"/>",
            "//36   </esi:otherwise>",
            "//37   </esi:choose>",
            "//38   <!-- ESI cdn script include for www -->",
            "//39   <script type=\"text/javascript\" src='<esi:include src=\"http://www.abcinclude.com\"></esi:include>/clientlibs/abc.min.js'></script>"
        ],
        "environmentVariables": [
            "versionPath: version",
            "currenthost: www.abc.com",
            "HTTP_ACCEPT: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8;",
            "HTTP_CONTENT_LENGTH: 14041",
            "HTTP_CONTENT_LOCATION:",
            "HTTP_CONTENT_TYPE: text/html; charset=UTF-8",
            "HTTP_COOKIE: Akamai-EncDebug=YZAWlx49ShMvQf5gbQ4N3xWhdCLgWM9x+2Z7B9hXbSuWLq82tq6g/qKXYCv4nHQ83bMFeqxrS8xEmlTfwkYyFj3HRcsAO0q7tt+KHwrN9HbZvpyxa7TDY7nrAvVkwCZ2rhhapcdaI6jkcw4lfCw7GUfdJneseiy0dOAxp0TiyE24q5JtKd+zGMad9Scc2YXQbrK6eBWdMdI=",
            "HTTP_HOST: www.abc.com",
            "HTTP_REFERER:"
        ],
        "syntaxErrorMessages": [],
        "evaluatedResults": [
            "[2004]: Your code ran successfully."
        ]
    },
    "allIncludedPages": [
        {
            "pageLink": "www.abc.com/content/test.html",
            "enumeratedSource": [
                "//1   <div class=\"test-class1\" id=\"test1\">",
                "//2   <esi:assign name=\"versionPath\" value=\"version\"/>",
                "//3   <div>Included Page 1</div>  "
            ],
            "environmentVariables": [
                "versionPath: version",
                "currenthost: www.abctest1.com"
            ],
            "syntaxErrorMessages": [],
            "evaluatedResults": [
                "[2011]: The document contains no ESI tags.",
                "[2004]: Your code ran successfully."
            ]
        },
        {
            "pageLink": "www.abc.com/content/abc/esi.html",
            "enumeratedSource": [
                "//1   <div class=\"test-class1\" id=\"test1\">",
                "//2   <esi:assign name=\"versionPath\" value=\"version\"/>",
                "//3   <div>Included Page 2</div>"
            ],
            "environmentVariables": [
                "versionPath: version",
                "currenthost: www.abctest2.com"
            ],
            "syntaxErrorMessages": [],
            "evaluatedResults": [
                "[2011]: The document contains no ESI tags.",
                "[2004]: Your code ran successfully."
            ]
        }
    ]
}

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.

Query

Contains the POST body parameters of the request for which you request ESI debugging information.

Download schema: inputBody.json

Sample POST request:

{
    "url": "https://www.abc.com",
    "clientRequestHeaders": {
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8;"
    },
    "clientIP": "192.168.76.67",
    "originServer": "test.server"
}

Query members

Member Type Required Description
clientIP String The client IP that emulates a location for specific EdgeScape GEO (geographic) data.
clientRequestHeaders Query.clientRequestHeaders Custom HTTP headers used in the client’s requests.
originServer String The test origin server where the edge server sends requests instead of the origin server.
url String The URL of the page with the ESI tags for which you request debugging information.

Report

Contains ESI debugging information for the source page and the included pages.

Download schema: esiDebugReport.json

Sample POST response:

{
    "sourceDebugPage": {
        "pageLink": "http://www.abc.com/",
        "enumeratedSource": [
            "//1    ",
            "//2    <!DOCTYPE html><html class=\"no-js\">",
            "//3    <head>",
            "//4    <meta charset=\"utf-8\">",
            "//5   <esi:choose>",
            "//6   <esi:when test=\"$len($(HTTP_HOST{0}))>1\">",
            "//21   <esi:assign name=\"currenthost\" value=\"$(HTTP_HOST{0})\"/>",
            "//22   </esi:when>",
            "//23   <esi:otherwise>",
            "//24   <esi:assign name=\"currenthost\" value=\"$(HTTP_HOST)\"/>",
            "//25   </esi:otherwise>",
            "//26   </esi:choose>",
            "//27   <esi:choose>",
            "//28   <esi:when test=\"$substr( $(currenthost), 0, $index($(currenthost), '.')) == inactive\">",
            "//29   <esi:assign name=\"versionPath\" value=\"inactiveversion\"/>",
            "//30   </esi:when>",
            "//31   <esi:when test=\"$substr( $(currenthost), 0, $index($(currenthost), '.')) == deploy\">",
            "//32   <esi:assign name=\"versionPath\" value=\"inactiveversion\"/>",
            "//33   </esi:when>",
            "//34   <esi:otherwise>",
            "//35   <esi:assign name=\"versionPath\" value=\"version\"/>",
            "//36   </esi:otherwise>",
            "//37   </esi:choose>",
            "//38   <!-- ESI cdn script include for www -->",
            "//39   <script type=\"text/javascript\" src='<esi:include src=\"http://www.abcinclude.com\"></esi:include>/clientlibs/abc.min.js'></script>"
        ],
        "environmentVariables": [
            "versionPath: version",
            "currenthost: www.abc.com",
            "HTTP_ACCEPT: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8;",
            "HTTP_CONTENT_LENGTH: 14041",
            "HTTP_CONTENT_LOCATION:",
            "HTTP_CONTENT_TYPE: text/html; charset=UTF-8",
            "HTTP_COOKIE: Akamai-EncDebug=YZAWlx49ShMvQf5gbQ4N3xWhdCLgWM9x+2Z7B9hXbSuWLq82tq6g/qKXYCv4nHQ83bMFeqxrS8xEmlTfwkYyFj3HRcsAO0q7tt+KHwrN9HbZvpyxa7TDY7nrAvVkwCZ2rhhapcdaI6jkcw4lfCw7GUfdJneseiy0dOAxp0TiyE24q5JtKd+zGMad9Scc2YXQbrK6eBWdMdI=",
            "HTTP_HOST: www.abc.com",
            "HTTP_REFERER:"
        ],
        "syntaxErrorMessages": [],
        "evaluatedResults": [
            "[2004]: Your code ran successfully."
        ]
    },
    "allIncludedPages": [
        {
            "pageLink": "www.abc.com/content/test.html",
            "enumeratedSource": [
                "//1   <div class=\"test-class1\" id=\"test1\">",
                "//2   <esi:assign name=\"versionPath\" value=\"version\"/>",
                "//3   <div>Included Page 1</div>  "
            ],
            "environmentVariables": [
                "versionPath: version",
                "currenthost: www.abctest1.com"
            ],
            "syntaxErrorMessages": [],
            "evaluatedResults": [
                "[2011]: The document contains no ESI tags.",
                "[2004]: Your code ran successfully."
            ]
        },
        {
            "pageLink": "www.abc.com/content/abc/esi.html",
            "enumeratedSource": [
                "//1   <div class=\"test-class1\" id=\"test1\">",
                "//2   <esi:assign name=\"versionPath\" value=\"version\"/>",
                "//3   <div>Included Page 2</div>"
            ],
            "environmentVariables": [
                "versionPath: version",
                "currenthost: www.abctest2.com"
            ],
            "syntaxErrorMessages": [],
            "evaluatedResults": [
                "[2011]: The document contains no ESI tags.",
                "[2004]: Your code ran successfully."
            ]
        }
    ]
}

Report members

Member Type Required Description
allIncludedPages Array ESI debugging information for all the pages that are included in the source page’s ESI code.
sourceDebugPage Object ESI debugging information for the source page.

Page

Contains ESI debugging information for a single page.

Download schema: esiDebugPage.json

Page members

Member Type Required Description
enumeratedSource Array The ESI source code lines with line numbers prefixed to each line.
environmentVariables Array The resulting values for the ESI-supported and user-defined variables.
evaluatedResults Array The results of evaluating the ESI source code.
pageLink String The URL of the page.
syntaxErrorMessages Array Information about any syntax error messages.

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

When the API encounters a problem, it responds with an object that adheres to the HTTP Problem Details standard. This sample shows an incorrect input error, where the type value defines the type of problem, and the instance may be useful if you need to communicate about the problem with your Akamai support representative: It also includes an optional errors array that lists potentially more than one problem detected in the request.

{
  "type": "EsiDebuggerInputException",
  "title": "Input Exception",
  "instance": "50d9286f-5453-4ba4-8e40-daa82deda609",
  "status": 400,
  "errors": [
    {
      "type": "EsiDebuggerInputException",
      "title": "Input Exception",
      "detail": "Invalid ClientIP"
    },
    {
      "type": "EsiDebuggerInputException",
      "title": "Input Exception",
      "detail": "Invalid Origin Server Hostname"
    }
  ]
}
}

HTTP status codes

Code Description
200 The operation was successful.
400 Bad Request.
403 Access is forbidden.
404 Resource not found.
500 Internal server error.

Last modified: 8/24/2018