Edge Hostnames API v1

Manage how requests for your site, app, or content are mapped to Akamai edge servers.

Learn more:

Overview

The Edge Hostnames API (HAPI) manages how requests for your site, app, or content are mapped to Akamai edge servers. An edge hostname is the CNAME target you use when directing your end user traffic to Akamai. In a typical DNS CNAME, your www.customer.com hostname corresponds to an edge hostname of www.customer.com.edgesuite.net.

Use the Property Manager API (PAPI) to create edge hostnames in order to align with the Property Manager product, IP version, and security settings. Use HAPI to get existing edge hostnames, edit edge hostname details such as IP version and TTL, and delete edge hostnames.

Get 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 Edge Hostnames API (HAPI), and set the access level to READ-WRITE.

Resources

This section provides details on each API operation. The following provides a road map of all the conceptual objects you deal with when interacting with the Edge Hostnames API (HAPI), and provides links to where you can learn more.

  • EdgeHostname: You can retrieve an EdgeHostname or an array of edge hostnames in order to view the change requests, status of change requests, or certificates associated with it. Each hostname assigned to a property corresponds to an Akamai edge hostname, which is typically the hostname suffixed with edgesuite.net over HTTP or edgekey.net over secure HTTPS. For example, your source hostname m.example.com corresponds by default to the edge hostname m.example.com.edgesuite.net. This interface specifies the full set of edge hostnames under your control, regardless of how they are assigned to various properties or property versions.

  • Certificate: You can retrieve a Certificate associated with an edge hostname to view its details.

  • ChangeRequest: You can retrieve a ChangeRequest or an array of change requests in order to view their details or status. Change requests signify a change made to an edge hostname.

  • Products: You can retrieve a list of Products to view the product names and product IDs of the products associated with an edge hostname.

  • Localization: You can retrieve the Localization strings in order to help you translate error messages.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List edge hostnames GET /hapi/v1/edge-hostnames{?recordNameSubstring,dnsZone,securityType,slotNumber,ttl,chinaCdnEnabled,isEdgeIPBindingEnabled,map,mapAlias,customTarget,comments}
Get an edge hostname GET /hapi/v1/edge-hostnames/{edgeHostnameId}
Get an edge hostname by DNS zone and record name GET /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}
Delete an edge hostname DELETE /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}{?statusUpdateEmail,comments}
Patch an edge hostname PATCH /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}{?statusUpdateEmail,comments}
List change requests per edge hostname GET /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}/change-requests
Get a certificate GET /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}/certificate
List change requests GET /hapi/v1/change-requests{?status}
Get a change request GET /hapi/v1/change-requests/{changeId}
List products GET /hapi/v1/products/display-names
Get localization data GET /hapi/v1/i18n/{language}

List edge hostnames

Lists all edge hostnames available for the logged-in account and context, optionally filtering results along several dimensions.

GET /hapi/v1/edge-hostnames{?recordNameSubstring,dnsZone,securityType,slotNumber,ttl,chinaCdnEnabled,isEdgeIPBindingEnabled,map,mapAlias,customTarget,comments}

Sample: /hapi/v1/edge-hostnames?recordNameSubstring=www.example.com&dnsZone=edgesuite.net&securityType=STANDARD-TLS&slotNumber=140&ttl=21600&chinaCdnEnabled=true&isEdgeIPBindingEnabled=true&map=a%3Bg.akamai.net&mapAlias=a%3Bg4.akamai.net&customTarget=www.example-eip.com.eip.akadns.net&comments=Created%20for%20site

Parameter Type Sample Description
Optional query parameters
chinaCdnEnabled Boolean true Filter by chinaCdnEnabled status.
comments String Created for site Filter by comments value.
customTarget String www.example-eip.com.eip.akadns.net Filter by customTarget value.
dnsZone String edgesuite.net Filter by dnsZone value.
isEdgeIPBindingEnabled Boolean true Filter by isEdgeIPBindingEnabled status.
map String a;g.akamai.net Filter by map value.
mapAlias String a;g4.akamai.net Filter by mapAlias value.
recordNameSubstring String www.example.com Filter by domain prefix substring.
securityType Enumeration STANDARD-TLS Filter by securityType value, either STANDARD-TLS or ENHANCED-TLS.
slotNumber Integer 140 Filter by slotNumber value.
ttl Integer 21600 Filter by ttl setting, in seconds.

Status 200 application/json

Object type: EdgeHostname

Download schema: edge-hostname-list.json

Response body:

{
    "edgeHostnames": [
        {
            "edgeHostnameId": 1,
            "recordName": "www.example.com",
            "dnsZone": "edgekey.net",
            "securityType": "ENHANCED-TLS",
            "useDefaultTtl": true,
            "useDefaultMap": true,
            "ipVersionBehavior": "IPV6_IPV4_DUALSTACK",
            "productId": "DSD",
            "ttl": 21600,
            "map": "e;dscb.akamaiedge.net",
            "slotNumber": 11838,
            "comments": "Created for example.com"
        },
        {
            "edgeHostnameId": 2,
            "recordName": "www.examples.com",
            "dnsZone": "edgesuite.net",
            "securityType": "STANDARD-TLS",
            "useDefaultTtl": true,
            "useDefaultMap": true,
            "ipVersionBehavior": "IPV4",
            "productId": "DSA",
            "ttl": 21600,
            "map": "a;g.akamai.net",
            "serialNumber": 140,
            "comments": "Created for site"
        },
        {
            "edgeHostnameId": 3,
            "recordName": "www.example-china.com",
            "dnsZone": "edgesuite.net",
            "useDefaultTtl": true,
            "useDefaultMap": true,
            "securityType": "STANDARD-TLS",
            "ipVersionBehavior": "IPV4",
            "productId": "DSA",
            "ttl": 1800,
            "map": "a;g.akamai.net",
            "serialNumber": 2322,
            "customTarget": "www.example-china.com.edgesuite.net.globalredir.akadns.net",
            "comments": "Created for China CDN",
            "chinaCdn": {
                "isChinaCdn": true
            }
        },
        {
            "edgeHostnameId": 4,
            "recordName": "www.example-eip.com",
            "dnsZone": "edgekey.net",
            "useDefaultTtl": true,
            "useDefaultMap": true,
            "securityType": "ENHANCED-TLS",
            "ipVersionBehavior": "IPV4",
            "productId": "DSA",
            "ttl": 21600,
            "isEdgeIPBindingEnabled": true,
            "slotNumber": 2322,
            "customTarget": "www.example-eip.com.eip.akadns.net",
            "comments": "Created for EIP"
        }
    ]
}

  1. Make a GET request to /hapi/v1/edge-hostnames{?recordNameSubstring,dnsZone,slotNumber,ttl,chinaCdnEnabled,isEdgeIPBindingEnabled,map,mapAlias,customTarget,comments}.

  2. To filter down the results, set any of the optional query parameters listed in the Parameters section.

  3. The response produces an array of EdgeHostname objects.

Get an edge hostname

Get a specific edge hostname’s details including its product ID, IP version behavior, and China CDN or Edge IP Binding status.

GET /hapi/v1/edge-hostnames/{edgeHostnameId}

Sample: /hapi/v1/edge-hostnames/3

Parameter Type Sample Description
URL path parameters
edgeHostnameId Integer 3 Unique identifier for an edge hostname.

Status 200 application/json

Object type: EdgeHostname

Download schema: edge-hostname.json

Response body:

{
    "edgeHostnameId": 1,
    "recordName": "www.example.com",
    "dnsZone": "edgekey.net",
    "securityType": "ENHANCED-TLS",
    "useDefaultTtl": true,
    "useDefaultMap": true,
    "ipVersionBehavior": "IPV6_IPV4_DUALSTACK",
    "productId": "DSD",
    "ttl": 21600,
    "map": "e;dscb.akamaiedge.net",
    "slotNumber": 11838,
    "comments": "Created for example.com"
}

  1. Run the List edge hostnames operation, choose the appropriate object, and store its edgeHostnameId..

  2. Make a GET request to /hapi/v1/edge-hostnames/{edgeHostnameId}.

  3. The operation responds with an EdgeHostname object.

Get an edge hostname by DNS zone and record name

Get the full record for a single edge hostname, as specified by its DNS zone and record name. You can view details such as product ID, IP version behavior, China CDN status, or Edge IP Binding status.

GET /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}

Sample: /hapi/v1/dns-zones/edgesuite.net/edge-hostnames/www.examples.com

Parameter Type Sample Description
URL path parameters
dnsZone String edgesuite.net DNS zone of the edge hostname.
recordName String www.examples.com Record name of the edge hostname.

Status 200 application/json

Object type: EdgeHostname

Download schema: edge-hostname.json

Response body:

{
    "edgeHostnameId": 1,
    "recordName": "www.example.com",
    "dnsZone": "edgekey.net",
    "securityType": "ENHANCED-TLS",
    "useDefaultTtl": true,
    "useDefaultMap": true,
    "ipVersionBehavior": "IPV6_IPV4_DUALSTACK",
    "productId": "DSD",
    "ttl": 21600,
    "map": "e;dscb.akamaiedge.net",
    "slotNumber": 11838,
    "comments": "Created for example.com"
}

  1. Run the List edge hostnames operation, choose the appropriate object, and store its dnsZone and recordName.

  2. Make a GET request to /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}.

  3. The operation responds with an EdgeHostname object.

Delete an edge hostname

Delete a specific edge hostname. You must have an Admin or Technical role in order to delete an edge hostname. You can delete any hostname that’s not currently part of an active Property Manager configuration.

DELETE /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}{?statusUpdateEmail,comments}

Sample: /hapi/v1/dns-zones/edgesuite.net/edge-hostnames/www.examples.com?statusUpdateEmail=someperson%40example.com&comments=done%20in%20haste%2C%20regretted%20at%20leisure

Parameter Type Sample Description
URL path parameters
dnsZone String edgesuite.net DNS zone of the edge hostname.
recordName String www.examples.com Record name of the edge hostname.
Optional query parameters
comments String done in haste, regretted at leisure Additional comments to inform statusUpdateEmail recipients of the reason for the change.
statusUpdateEmail String someperson@example.com Repeatable. Email address that should receive updates on the change request. To specify more than one email address use a single comma-separated set of addresses, or repeat the parameter with each address.

Status 202 application/json

Headers:

Location: /hapi/v1/change-requests/62750978

Object type: ChangeRequest

Download schema: change-request.json

Response body:

{
    "action": "DELETE",
    "changeId": 1,
    "comments": "Delete for example.com",
    "status": "SUCCEEDED",
    "statusMessage": "File successfully deployed to Akamai's network",
    "statusUpdateDate": "2018-10-17T20:21:17.0Z",
    "statusUpdateEmail": "nobody@akamai.com",
    "submitDate": "2018-10-17T20:21:12.0Z",
    "submitter": "nobody",
    "submitterEmail": "nobody@akamai.com",
    "edgeHostnames": [
        {
            "edgeHostnameId": 1,
            "recordName": "www.example.com",
            "dnsZone": "edgekey.net",
            "securityType": "ENHANCED-TLS",
            "useDefaultTtl": false,
            "useDefaultMap": false,
            "ttl": 21600,
            "map": "e;b.akamaiedge.net",
            "slotNumber": 11838,
            "ipVersionBehavior": "IPV4",
            "comments": "Edited for Super Bowl"
        }
    ]
}

  1. Run the List edge hostnames operation, choose the appropriate object, and store the dnsZone and recordName URL parameters.

  2. Optionally, set the statusUpdateEmail query parameter to the addresses you wish to notify when updates occur.

  3. Optionally, set the comments query parameter to include any comments about the edge hostname being deleted.

  4. Make a DELETE request to /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}{?statusUpdateEmail,comments}.

  5. The operation responds with a ChangeRequest object, which the Location response header links to.

Patch an edge hostname

Selectively modify an edge hostname using JSON patch syntax. This API supports the replace patch operation to make simple changes to the TTL and IP version.

PATCH /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}{?statusUpdateEmail,comments}

Sample: /hapi/v1/dns-zones/edgesuite.net/edge-hostnames/www.examples.com?statusUpdateEmail=someperson%40example.com&comments=done%20in%20haste%2C%20regretted%20at%20leisure

Content-Type: application/json-patch+json

Download schema: edge-hostname-patch.json

Request body:

[
    {
        "op": "replace",
        "path": "/ttl",
        "value": "500"
    },
    {
        "op": "replace",
        "path": "/ipVersionBehavior",
        "value": "IPV4"
    }
]
Parameter Type Sample Description
URL path parameters
dnsZone String edgesuite.net DNS zone of the edge hostname.
recordName String www.examples.com Record name of the edge hostname.
Optional query parameters
comments String done in haste, regretted at leisure Additional comments to inform statusUpdateEmail recipients of the reason for the change.
statusUpdateEmail String someperson@example.com Repeatable. Email address that should receive updates on the change request. To specify more than one email address use a single comma-separated set of addresses, or repeat the parameter with each address.

Status 202 application/json

Headers:

Location: /hapi/v1/change-requests/62750978

Object type: ChangeRequest

Download schema: change-request.json

Response body:

{
    "action": "EDIT",
    "changeId": 53494819,
    "edgeHostnames": [
        {
            "edgeHostnameId": 1803728,
            "recordName": "amp.nfl.com",
            "dnsZone": "edgekey.net",
            "securityType": "ENHANCED-TLS",
            "useDefaultMap": false,
            "useDefaultTtl": false,
            "ttl": 21600,
            "map": "e;b.akamaiedge.net",
            "slotNumber": 91899,
            "comments": "Edited for Super Bowl"
        }
    ],
    "comments": "Editing CNAME",
    "status": "PENDING",
    "statusUpdateDate": "2016-11-18T20:21:17.0Z",
    "statusUpdateEmail": "bbuenave@akamai.com",
    "submitDate": "2016-11-18T20:21:12.0Z",
    "submitter": "bbuenave",
    "submitterEmail": "bbuenave@akamai.com"
}

  1. Run the List edge hostnames operation, choose the appropriate object, and store the dnsZone and recordName URL parameters.

  2. Optionally, set the statusUpdateEmail query parameter to the addresses you wish to notify when updates occur.

  3. Optionally, set the comments query parameter to include any comments about the edge hostname being edited.

  4. Form an array of JSON patch objects to replace the EdgeHostname’s ttl or ipVersionBehavior values.

  5. Submit a PATCH request with the JSON patch array to /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}{?statusUpdateEmail,comments}.

  6. The operation responds with a ChangeRequest object, which the Location response header links to.

List change requests per edge hostname

Get the list of all change requests made for the specified edge hostname.

GET /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}/change-requests

Sample: /hapi/v1/dns-zones/edgesuite.net/edge-hostnames/www.examples.com/change-requests

Parameter Type Sample Description
URL path parameters
dnsZone String edgesuite.net DNS zone of the edge hostname.
recordName String www.examples.com Record name of the edge hostname.

Status 200 application/json

Object type: ChangeRequest

Download schema: change-request-list.json

Response body:

{
    "changeRequests": [
        {
            "action": "EDIT",
            "changeId": 2,
            "comments": "Editing CNAME",
            "status": "PENDING",
            "statusMessage": "File uploaded and awaiting validation",
            "statusUpdateDate": "2018-10-17T20:21:17.0Z",
            "statusUpdateEmail": "nobody@akamai.com",
            "submitDate": "2018-10-17T20:21:12.0Z",
            "submitter": "nobody",
            "submitterEmail": "nobody@akamai.com",
            "edgeHostnames": [
                {
                    "edgeHostnameId": 2,
                    "recordName": "www.examples.com",
                    "dnsZone": "edgesuite.net",
                    "securityType": "STANDARD-TLS",
                    "useDefaultTtl": true,
                    "useDefaultMap": true,
                    "ipVersionBehavior": "IPV4",
                    "productId": "DSA",
                    "ttl": 21600,
                    "map": "a;g.akamai.net",
                    "serialNumber": 140,
                    "comments": "Created for site"
                }
            ]
        },
        {
            "action": "CREATE",
            "changeId": 1,
            "comments": "Created for example.com",
            "status": "PENDING",
            "statusMessage": "File uploaded and awaiting validation",
            "statusUpdateDate": "2018-10-17T20:21:17.0Z",
            "statusUpdateEmail": "nobody@akamai.com",
            "submitDate": "2018-10-17T20:21:12.0Z",
            "submitter": "nobody",
            "submitterEmail": "nobody@akamai.com",
            "edgeHostnames": [
                {
                    "edgeHostnameId": 1,
                    "recordName": "www.example.com",
                    "dnsZone": "edgekey.net",
                    "securityType": "ENHANCED-TLS",
                    "useDefaultTtl": false,
                    "useDefaultMap": false,
                    "ttl": 21600,
                    "map": "e;b.akamaiedge.net",
                    "slotNumber": 11838,
                    "ipVersionBehavior": "IPV4",
                    "comments": "Edited for Super Bowl"
                }
            ]
        }
    ]
}

  1. Run the List edge hostnames operation, choose the appropriate object, and store the dnsZone and recordName URL parameters.

  2. Make a GET request to /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}/change-requests.

  3. The operation responds with an object whose changeRequests array lists the set of ChangeRequest objects.

Get a certificate

Get the certificate associated with an enhanced TLS edge hostname.

GET /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}/certificate

Sample: /hapi/v1/dns-zones/edgesuite.net/edge-hostnames/www.examples.com/certificate

Parameter Type Sample Description
URL path parameters
dnsZone String edgesuite.net DNS zone of the edge hostname.
recordName String www.examples.com Record name of the edge hostname.

Status 200 application/json

Object type: Certificate

Download schema: certificate.json

Response body:

{
    "certificateId": "1234",
    "commonName": "example.com",
    "serialNumber": "12:34:56:78:90:AB:CD:EF",
    "slotNumber": 8927,
    "expirationDate": "2019-10-31T23:59:59Z",
    "certificateType": "SAN",
    "validationType": "DOMAIN_VALIDATION",
    "status": "PENDING",
    "availableDomains": [
        "live.example.com",
        "secure.example.com",
        "www.example.com"
    ]
}

  1. Run the List edge hostnames operation, choose the appropriate object, and store the dnsZone and recordName URL parameters.

  2. Make a GET request to /hapi/v1/dns-zones/{dnsZone}/edge-hostnames/{recordName}/certificate.

  3. The operation responds with a Certificate object.

List change requests

Get the list of pending change requests for the logged-in account and context.

GET /hapi/v1/change-requests{?status}

Sample: /hapi/v1/change-requests?status=PENDING

Parameter Type Sample Description
Optional query parameters
status Enumeration PENDING Status of change requests to retrieve. The only currently available value is PENDING.

Status 200 application/json

Object type: ChangeRequest

Download schema: change-request-list.json

Response body:

{
    "changeRequests": [
        {
            "action": "EDIT",
            "changeId": 2,
            "comments": "Editing CNAME",
            "status": "PENDING",
            "statusMessage": "File uploaded and awaiting validation",
            "statusUpdateDate": "2018-10-17T20:21:17.0Z",
            "statusUpdateEmail": "nobody@akamai.com",
            "submitDate": "2018-10-17T20:21:12.0Z",
            "submitter": "nobody",
            "submitterEmail": "nobody@akamai.com",
            "edgeHostnames": [
                {
                    "edgeHostnameId": 2,
                    "recordName": "www.examples.com",
                    "dnsZone": "edgesuite.net",
                    "securityType": "STANDARD-TLS",
                    "useDefaultTtl": true,
                    "useDefaultMap": true,
                    "ipVersionBehavior": "IPV4",
                    "productId": "DSA",
                    "ttl": 21600,
                    "map": "a;g.akamai.net",
                    "serialNumber": 140,
                    "comments": "Created for site"
                }
            ]
        },
        {
            "action": "CREATE",
            "changeId": 1,
            "comments": "Created for example.com",
            "status": "PENDING",
            "statusMessage": "File uploaded and awaiting validation",
            "statusUpdateDate": "2018-10-17T20:21:17.0Z",
            "statusUpdateEmail": "nobody@akamai.com",
            "submitDate": "2018-10-17T20:21:12.0Z",
            "submitter": "nobody",
            "submitterEmail": "nobody@akamai.com",
            "edgeHostnames": [
                {
                    "edgeHostnameId": 1,
                    "recordName": "www.example.com",
                    "dnsZone": "edgekey.net",
                    "securityType": "ENHANCED-TLS",
                    "useDefaultTtl": false,
                    "useDefaultMap": false,
                    "ttl": 21600,
                    "map": "e;b.akamaiedge.net",
                    "slotNumber": 11838,
                    "ipVersionBehavior": "IPV4",
                    "comments": "Edited for Super Bowl"
                }
            ]
        }
    ]
}

  1. Run the List edge hostnames operation, choose the appropriate object, and store the dnsZone and recordName URL parameters.

  2. Optionally, set the status query parameter to PENDING to include only pending change requests.

  3. Make a GET request to /hapi/v1/change-requests{?status}.

  4. The operation responds with an array of ChangeRequest objects.

Get a change request

Get a change request status and details specified by the change ID provided when you make a change request.

GET /hapi/v1/change-requests/{changeId}

Sample: /hapi/v1/change-requests/2

Parameter Type Sample Description
URL path parameters
changeId Integer 2 Unique identifier for a change request.

Status 200 application/json

Object type: ChangeRequest

Download schema: change-request.json

Response body:

{
    "action": "CREATE",
    "changeId": 1,
    "comments": "Created for example.com",
    "status": "SUCCEEDED",
    "statusMessage": "File successfully deployed to Akamai's network",
    "statusUpdateDate": "2018-10-17T20:21:17.0Z",
    "statusUpdateEmail": "nobody@akamai.com",
    "submitDate": "2018-10-17T20:21:12.0Z",
    "submitter": "nobody",
    "submitterEmail": "nobody@akamai.com",
    "edgeHostnames": [
        {
            "edgeHostnameId": 1,
            "recordName": "www.example.com",
            "dnsZone": "edgekey.net",
            "securityType": "ENHANCED-TLS",
            "useDefaultTtl": false,
            "useDefaultMap": false,
            "ttl": 21600,
            "map": "e;b.akamaiedge.net",
            "slotNumber": 11838,
            "ipVersionBehavior": "IPV4",
            "comments": "Edited for Super Bowl"
        }
    ]
}

  1. Run the List change requests operation, choose the appropriate object, and store the changeId URL parameter.

  2. Make a GET request to /hapi/v1/change-requests/{changeId}.

  3. The operation responds with a ChangeRequest object.

List products

Get the list of product IDs and their corresponding display names for products this API supports.

GET /hapi/v1/products/display-names

Status 200 application/json

Object type: Products

Download schema: product-display-names.json

Response body:

{
    "productDisplayNames": [
        {
            "productId": "Alta",
            "productDisplayName": "Protect & Perform"
        },
        {
            "productId": "DSD",
            "productDisplayName": "Site Delivery"
        }
    ]
}

  1. Make a GET request to /hapi/v1/products/display-names.

  2. The operation responds with a Products object.

  3. You can choose from the object’s Products.productDisplayNames[] array.

Get localization data

Get the collection of application property strings in a specific language.

GET /hapi/v1/i18n/{language}

Sample: /hapi/v1/i18n/de_DE

Parameter Type Sample Description
URL path parameters
language Enumeration de_DE The supported language values are de_DE for German, en_US for English, es_ES for Spanish, es_LA for Spanish for Latin America, fr_FR for French, it_IT for Italian, ja_JP for Japanese, ko_KR for Korean, pt_BR for Brazilian Portuguese, zh_CNfor Simplified Chinese, and zh_TW for Traditional Chinese.

Status 200 application/json

Object type: Localization

Download schema: i18n.json

Response body:

{
    "hapi": {
        "problems": {
            "edge-hostname-id-not-found": {
                "detail": "Could not find edgeHostnameId: {{edgeHostnameId}}",
                "title": "Invalid EdgeHostname Id"
            },
            "invalid-ttl": {
                "detail": "TTL is required and should be a number between 0 and 86400",
                "title": "TTL is Invalid"
            }
        }
    }
}

  1. Choose one of the available language strings listed in the operation’s Parameters section.

  2. Make a GET request to /hapi/v1/i18n/{language}.

  3. The response exactly matches a Localization object.

Data

This section provides details for each type of data object the API exchanges. All of the objects are read-only.

Download the JSON schemas for this API.

EdgeHostname

Specifies a set of available hostnames to which a property version may be applied.

Download schema: edge-hostname.json

Sample GET response:

{
    "edgeHostnameId": 1,
    "recordName": "www.example.com",
    "dnsZone": "edgekey.net",
    "securityType": "ENHANCED-TLS",
    "useDefaultTtl": true,
    "useDefaultMap": true,
    "ipVersionBehavior": "IPV6_IPV4_DUALSTACK",
    "productId": "DSD",
    "ttl": 21600,
    "map": "e;dscb.akamaiedge.net",
    "slotNumber": 11838,
    "comments": "Created for example.com"
}

EdgeHostname members

Member Type Description
EdgeHostname: Specifies a set of available hostnames to which a property version may be applied.
chinaCdn EdgeHostname.chinaCdn Indicates whether the edge hostname can serve traffic in China.
comments String The comments provided upon the creation of the edge hostname (via Property Manager or Property Manager API).
customTarget String The custom targets of the edge hostname. A custom target is a user-specified target for the edge hostname.
dnsZone String The Akamai-specific portion of the edge hostname, for example the edgesuite.net portion of www.example.com.edgesuite.net.
edgeHostnameId Integer The edge hostname’s unique identifier, which you can assign to a property.
ipVersionBehavior Enumeration Which version of the IP protocol to use: IPV4 for version 4 only, IPV6 for version 6 only, or IPV6_IPV4_DUALSTACK for both 4 and 6.
isEdgeIPBindingEnabled Boolean Indicates whether Edge IP Binding is enabled. Edge IP Binding helps deliver traffic from fixed IP addresses in a scalable manner.
map String The correlation between your edge hostname and the IP address that the hostname resolves to.
mapAlias String An alternate name for a map. Can be used to establish a different time to live (TTL) for the same map, for example.
productId String A unique identifier for the product associated with the edge hostname.
recordName String The origin domain portion of the edge hostname, for example the www.example.com portion of www.example.com.edgesuite.net.
securityType Enumeration Indicates whether STANDARD-TLS or ENHANCED-TLS security applies to this edge hostname.
serialNumber Integer The serial number for the standard-tls hostname.
slotNumber Integer Sets the slot number for the enhanced-tls hostnames. Only applies when securityType is set to ENHANCED-TLS.
ttl Integer The time to live, or number of seconds to keep an edge hostname assigned to a map or target. This determines how long it takes for changes to the edge hostname to take effect.
useCases EdgeHostname.useCases[] Specifies a set of Akamai-provided preset use case scenarios to help optimize different types of traffic. You can assign use cases when creating a new edge hostname in the Property Manager API (PAPI). For details, see Assign a use case to an edge hostname.
useDefaultMap Boolean Indicates if the product’s default map is being used or not.
useDefaultTtl Boolean Indicates if the product’s default TTL (time to live) settings are being used for the edge hostname or if a custom one has been set.
EdgeHostname.chinaCdn: Indicates whether the edge hostname can serve traffic in China.
customChinaCdnMap String Shows the custom China CDN map you are using, if applicable.
isChinaCdn Boolean Indicates whether the edge hostname can serve traffic in China.
EdgeHostname.useCases[]: Specifies a set of Akamai-provided preset use case scenarios to help optimize different types of traffic. You can assign use cases when creating a new edge hostname in the Property Manager API (PAPI). For details, see Assign a use case to an edge hostname.
option String Specifies one of the use case’s available options that help specify the type of traffic.
type Enumeration Identifies the Akamai network over which traffic deploys. The only value currently available is the GLOBAL network.
useCase String A unique identifier for each use case.

Certificate

Contains an electronic document that includes a company’s identification information.

Download schema: certificate.json

Sample GET response:

{
    "certificateId": "1234",
    "commonName": "example.com",
    "serialNumber": "12:34:56:78:90:AB:CD:EF",
    "slotNumber": 8927,
    "expirationDate": "2019-10-31T23:59:59Z",
    "certificateType": "SAN",
    "validationType": "DOMAIN_VALIDATION",
    "status": "PENDING",
    "availableDomains": [
        "live.example.com",
        "secure.example.com",
        "www.example.com"
    ]
}

Certificate members

Member Type Description
Certificate: Contains an electronic document that includes a company’s identification information.
availableDomains Array List of available domains for the certificate. This includes the common name. Enhanced-TLS hostnames require a certificate.
certificateId String Unique identifier for the certificate.
certificateType Enumeration The certificate type. Can be SAN, SINGLE, THIRD_PARTY, WILDCARD, or WILDCARD_SAN. A SAN certificate supports multiple domain names, a SINGLE certificate associates with a single domain name, a THIRD_PARTY certificate uses a signed certificate that you obtain from a CA not integrated with Content Provisioning System (CPS), a WILDCARD certificate secures an entire domain, and a WILDCARD_SAN certificate uses wildcard certificates with Subject Alternative Names.
commonName String The hostname that the certificate is valid for, in addition to the hostnames in the list of available domains.
expirationDate String The ISO–8601 timestamp of the expiration date of the certificate.
serialNumber String The unique identifier for the certificate.
slotNumber Integer Sets the slot number for ENHANCED-TLS hostnames.
status Enumeration The status of the certificate. It can be PENDING, DEPLOYED, or EXPIRED.
validationType Enumeration The validation type used for the certificate. DOMAIN_VALIDATION is a lower level of validation which ensures you have control of the domain. ORGANIZATIONAL_VALIDATION is a higher level of validation which validates whether or not the company is valid, registered, and if the business contact works at the company. THIRD_PARTY is used for third party certificates. EXTENDED_VALIDATION is the highest level of validation for which you must have signed letters and notaries sent to the CA before signing. Wildcard certificates cannot be EV certificates.

ChangeRequest

Shows the status of the change request which signifies what type of change has been made to an edge hostname and if that change has happened.

Download schema: change-request.json

Sample GET response:

{
    "action": "CREATE",
    "changeId": 1,
    "comments": "Created for example.com",
    "status": "SUCCEEDED",
    "statusMessage": "File successfully deployed to Akamai's network",
    "statusUpdateDate": "2018-10-17T20:21:17.0Z",
    "statusUpdateEmail": "nobody@akamai.com",
    "submitDate": "2018-10-17T20:21:12.0Z",
    "submitter": "nobody",
    "submitterEmail": "nobody@akamai.com",
    "edgeHostnames": [
        {
            "edgeHostnameId": 1,
            "recordName": "www.example.com",
            "dnsZone": "edgekey.net",
            "securityType": "ENHANCED-TLS",
            "useDefaultTtl": false,
            "useDefaultMap": false,
            "ttl": 21600,
            "map": "e;b.akamaiedge.net",
            "slotNumber": 11838,
            "ipVersionBehavior": "IPV4",
            "comments": "Edited for Super Bowl"
        }
    ]
}

ChangeRequest members

Member Type Description
ChangeRequest: Shows the status of the change request which signifies what type of change has been made to an edge hostname and if that change has happened.
action Enumeration The action requested that is represented by the change request. Can be CREATE, EDIT, or DELETE.
changeId Integer The unique identifier for a specific change request.
comments String The comment added when the change request was created.
edgeHostnames EdgeHostname Array A list of all edge hostnames to which this change request applies.
status Enumeration The status of the change request. Can be PENDING, SUCCEEDED, FAILED, or IGNORED.
statusMessage String The API generates the status message to reflect the nature of the change request.
statusUpdateDate String The ISO–8601 timestamp indicating the time of the most recent status update.
statusUpdateEmail String The email that provides the status update.
submitDate String The ISO–8601 timestamp indicating the time of the submitted change request.
submitter String The username of the person who submitted the change request.
submitterEmail String The email address for the change request’s submitter. This is the email address that the statusUpdateEmail is sent to.

Products

Maps a set of product IDs to the display names it is associated with.

Download schema: product-display-names.json

Sample GET response:

{
    "productDisplayNames": [
        {
            "productId": "Alta",
            "productDisplayName": "Protect & Perform"
        },
        {
            "productId": "DSD",
            "productDisplayName": "Site Delivery"
        }
    ]
}

Products members

Member Type Description
Products: Maps a set of product IDs to the display names it is associated with.
productDisplayNames Products.productDisplayNames[] The list of product ID-to-name mappings.
Products.productDisplayNames[]: The list of product ID-to-name mappings.
productDisplayName String The display name.
productId String Unique identifier for the product.

Localization

Provides the ability to translate error messages.

Download schema: i18n.json

Sample GET response:

{
    "hapi": {
        "problems": {
            "edge-hostname-id-not-found": {
                "detail": "Could not find edgeHostnameId: {{edgeHostnameId}}",
                "title": "Invalid EdgeHostname Id"
            },
            "invalid-ttl": {
                "detail": "TTL is required and should be a number between 0 and 86400",
                "title": "TTL is Invalid"
            }
        }
    }
}

Localization members

Member Type Description
Localization: Provides the ability to translate error messages.
hapi Localization.hapi The top-level container for translations.
Localization.hapi: The top-level container for translations.
problems Localization.hapi.problems Contains specific error keys that correspond to the last segment of the error response’s type URL, title, and details and may include template text for items the API reports on at runtime.
Localization.hapi.problems: Contains specific error keys that correspond to the last segment of the error response’s type URL, title, and details and may include template text for items the API reports on at runtime.
{errorType} Localization.hapi.problems.{errorType} Anything else.
Localization.hapi.problems.{errorType}: Anything else.
detail String Short description of error.
title String Display name for the error case.

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

This API responds with JSON objects that adhere to the HTTP ProblemDetails standard.

{
    "errors": [],
    "instance": "/hapi/error-instances/60c61086-6089-41f9-867f-6bc4dbf24dee",
    "method": "GET",
    "requestInstance": "http://example1.example2.akamai.com/hapi/dns-zones/edgekey.net/edge-hostnames/www.akamai.com#8c2da36b",
    "requestTime": "2018-11-14T15:42:35.988Z",
    "status": 403,
    "title": "Access Denied to Edge Hostname",
    "type": "/hapi/problems/access-denied-to-edge-hostname"
}

HTTP status codes

This section lists the full range of response codes the API may generate. The Get localization data operation provides details on more specific error cases, each of which appears as the last segment of the error response’s type URL path.

Code Description
200 The operation was successful.
202 Resource successfully accepted.
400 Bad Request.
401 Authentication failure.
403 Access is forbidden.
404 Resource not found.
405 Method not supported.
408 Request timeout.
415 Unsupported media type.
429 Too many requests.
500 Internal server error.
502 Platform timeout error.
503 Too many requests. Service is temporarily unavailable.