API Endpoint Definition API Data

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

The object tables below reflect the same membership requirements as in JSON schema. For a data member to be marked required, you must provide it either in request objects, or ensure it is always present in responses. objects:

Member must to be present in all interaction contexts, regardless of whether the value is empty or null.
Member is optional, and may be omitted in some contexts.

Download the JSON schemas for this API.

EndpointList

This object provides a contextual wrapper to reflect details about the initial request for a collection of endpoints.

EndpointList Members

Member Type Required Description
apiEndPoints EndpointList.apiEndPoints[n] Each Endpoint reported in the collection.
page Integer Reflects the requested page number index.
pageSize Integer Reflects the requested number of API endpoints on each page of results.
totalSize Integer The total number of API endpoints available in the reported set.

EndpointList.apiEndPoints[n]  

Each Endpoint reported in the collection.

Member Type Required Description
apiCategoryIds Array, Null A list of Category identifiers that apply to this endpoint. The value may be null rather than an empty array for uncategorized endpoints.
apiEndPointHosts Array, Null A list of hostname strings that may receive traffic for this API. The value may be null rather than an empty array for disabled APIs.
apiEndPointId Integer A unique identifier for each endpoint.
apiEndPointLocked Boolean Read-only. Specifies if the endpoint version is editable or read only.
apiEndPointName String A name for the API service.
apiEndPointScheme Enumeration The URL scheme to which the endpoint may respond, either http, https, or http/https for both.
apiEndPointVersion Integer A unique identifier for each endpoint version.
apiResourceBaseInfo EndpointList.apiEndPoints[n].apiResourceBaseInfo[n] Encapsulates each Resource the API endpoint supports.
basePath String The URL path that serves as a root prefix for all resources’ resourcePath values. This is / if empty. Do not append a / character to the path.
clonedFromVersion Integer Read-only. A unique identifier version from which this was cloned.
consumeType Enumeration The content type the endpoint receives from requests, either json, xml, json/xml for dual-format APIs, any, or none.
createDate String Read-only. An ISO–6801 timestamp string indicating when the endpoint was initially created.
createdBy String Identifies who initially created the endpoint.
description String A description for the API service.
lockVersion Number An identifier used for optimistic locking. See Concurrency Control for details.
productionVersion EndpointList.apiEndPoints[n].productionVersion Read-only. The version currently activated on the staging network.
stagingVersion EndpointList.apiEndPoints[n].stagingVersion Read-only. The version currently activated on the staging network.
updateDate String Read-only. An ISO–6801 timestamp string indicating when the endpoint was most recently modified.
updatedBy String Identifies who last modified the endpoint.
versionNumber Integer Version number.

EndpointList.apiEndPoints[n].apiResourceBaseInfo[n]  

Encapsulates each Resource the API endpoint supports.

Member Type Required Description
apiResourceClonedFromId Integer A unique identifier for the resource from which it is cloned.
apiResourceId Integer Read-only. A unique identifier for each resource.
apiResourceLogicId Integer A unique identifier of the same resource across endpoint versions.
apiResourceName String A name for the resource.
createDate String Read-only. An ISO–6801 timestamp string indicating when the resource was initially created.
createdBy String Identifies who initially created the resource.
description String A description to clarify the resource’s function within the API.
link String The location of the navigable resource within this API, for use by API clients. See Hypermedia for details.
lockVersion Number The updateDate expressed as epoch milliseconds, used for optimistic locking. See Concurrency Control for details.
resourcePath String The URL template pattern, relative to the API’s basePath, to which this resource responds.
updateDate String Read-only. An ISO–6801 timestamp string indicating when the resource was most recently modified.
updatedBy String Identifies who last modified the resource.

EndpointList.apiEndPoints[n].productionVersion  

The version currently activated on the staging network.

Member Type Required Description
status Enumeration Network status, either PENDING or ACTIVE.
versionNumber Integer A unique identifier for each endpoint version.

EndpointList.apiEndPoints[n].stagingVersion  

The version currently activated on the staging network.

Member Type Required Description
status Enumeration Network status, either PENDING or ACTIVE.
versionNumber Integer A unique identifier for each endpoint version.

Endpoint

Encapsulates an endpoint.

Endpoint Members

Member Type Required Description
akamaiSecurityRestrictions Endpoint.akamaiSecurityRestrictions Collects various restrictions to apply to the endpoint.
apiCategoryIds Array, Null A list of Category identifiers that apply to this endpoint. The value may be null rather than an empty array for uncategorized endpoints.
apiEndPointHosts Array, Null A list of hostname strings that may receive traffic for this API. The value may be null rather than an empty array for disabled APIs.
apiEndPointId Integer Read-only. A unique identifier for each endpoint.
apiEndPointLocked Boolean Read-only. Specifies if the endpoint version is editable or read only.
apiEndPointName String A name for the API service.
apiEndPointScheme Enumeration The URL scheme to which the endpoint may respond, either http, https, or http/https, for both.
apiEndPointVersion Integer Read-only. A unique identifier for each endpoint version.
apiResourceBaseInfo Endpoint.apiResourceBaseInfo[n] Encapsulates each Resource the API endpoint supports.
basePath String The URL path that serves as a root prefix for all resources’ resourcePath values. This is / if empty. Do not append a / character to the path.
clonedFromVersion Integer Read-only. A unique identifier of the cloned version.
consumeType Enumeration The content type the endpoint exchanges, either json, xml, json/xml for dual-format APIs, any, or none.
contractId String Read-only. A unique identifier for the contract with Akamai under which security for this API is provisioned.
createDate String Read-only. An ISO–6801 timestamp string indicating when the endpoint was initially created.
createdBy String Identifies who initially created the endpoint.
description String A description for the API service.
groupId Integer Read-only. A unique identifier for the group in the Luna portal under which security for this API is provisioned.
lockVersion Number The updateDate expressed as epoch milliseconds, used for optimistic locking. See Concurrency Control for details.
productionVersion Endpoint.productionVersion Read-only. The version currently activated on the staging network.
securityScheme Endpoint.securityScheme Encapsulates information about the key with which users may access the API.
stagingVersion Endpoint.stagingVersion Read-only. The version currently activated on the staging network.
updateDate String Read-only. An ISO–6801 timestamp string indicating when the endpoint was most recently modified.
updatedBy String Identifies who last modified the endpoint.
versionNumber Integer Read-only. Endpoint version number.

Endpoint.akamaiSecurityRestrictions  

Collects various restrictions to apply to the endpoint.

Member Type Required Description
MAX_BODY_SIZE Integer Maximum size of the data payload.
MAX_DOC_DEPTH Integer Maximum depth of nested data elements.
MAX_ELEMENT_NAME_LENGTH Integer Maximum length of an XML element name or JSON object key name.
MAX_INTEGER_VALUE Integer Maximum numeric value within any exchanged data.
MAX_JSONXML_ELEMENT Integer Maximum allowed number of XML elements, or JSON object keys or array items.
MAX_STRING_LENGTH Integer Maximum length of any string value in a POST body.
POSTIVE_SECURITY_ENABLED Enumeration A numeric enumeration. When set to 1, allows specified body constraints and the set of defined resources to reflect as a Kona Site Defender whitelist policy. Otherwise set to 0 to disable.

Endpoint.apiResourceBaseInfo[n]  

Encapsulates each Resource the API endpoint supports.

Member Type Required Description
apiResourceClonedFromId Integer Read-only. A unique identifier for the resource from which it is cloned.
apiResourceId Number Read-only. A unique identifier for each resource.
apiResourceLogicId Integer Read-only. A unique identifier of the same cloned resource across endpoint versions.
apiResourceName String A name for the resource.
createDate String Read-only. An ISO–6801 timestamp string indicating when the resource was initially created.
createdBy String Identifies who initially created the resource.
description String A description to clarify the resource’s function within the API.
link String The location of the navigable resource within this API, for use by API clients. See Hypermedia for details.
lockVersion Number The updateDate expressed as epoch milliseconds, used for optimistic locking. See Concurrency Control for details.
resourcePath String The URL template pattern, relative to the API’s basePath, to which this resource responds.
updateDate String Read-only. An ISO–6801 timestamp string indicating when the resource was most recently modified.
updatedBy String Identifies who last modified the resource.

Endpoint.productionVersion  

The version currently activated on the staging network.

Member Type Required Description
status Enumeration Network status, either PENDING or ACTIVE.
versionNumber Integer A unique identifier for each endpoint version.

Endpoint.securityScheme  

Encapsulates information about the key with which users may access the API.

Member Type Required Description
securitySchemeDescription String Descriptive text to administer the security scheme.
securitySchemeDetail Endpoint.securityScheme.securitySchemeDetail Read-only. An object that locates and identifies the API key.
securitySchemeId Integer Read-only. A unique identifier for each security scheme.
securitySchemeType Enumeration Identifies the type of security scheme, for which currently the only valid value is apikey.

Endpoint.securityScheme.securitySchemeDetail  

An object that locates and identifies the API key.

Member Type Required Description
apiKeyName String The name of the header or query parameter that serves as the API key.

Endpoint.stagingVersion  

The version currently activated on the staging network.

Member Type Required Description
status Enumeration Network status, either PENDING or ACTIVE.
versionNumber Integer A unique identifier for each endpoint version.

Resource

Encapsulates each Resource the API endpoint supports.

Sample GET:

[
    {
        "apiResourceId": 123,
        "apiResourceName": "cloud security",
        "resourcePath": "/resources/security/{resourceId}",
        "description": "resource description",
        "link": "/api-definitions/v1/endpoints/111/resources/123",
        "createdBy": "jdoe",
        "createDate": "2013-10-07T17:41:52+0000",
        "updatedBy": "yauoid",
        "updateDate": "2013-10-07T17:41:52+0000",
        "lockVersion": 729179949,
        "apiResourceMethodNameLists": [
            "GET",
            "POST"
        ]
    },
    {
        "apiResourceId": 125,
        "apiResourceName": "cloud security image",
        "resourcePath": "/resources/security-image/{resourceId}",
        "description": "resource description2",
        "link": "/api-definitions/v1/endpoints/111/resources/125",
        "createdBy": "jdoe",
        "createDate": "2013-10-07T17:41:52+0000",
        "updatedBy": "rsmith",
        "updateDate": "2013-10-07T17:41:52+0000",
        "lockVersion": 729179949,
        "apiResourceMethodNameLists": [
            "GET",
            "POST"
        ]
    }
]

Resource Members

Member Type Required Description
apiResourceClonedFromId Integer Read-only. A unique identifier for the resource from which this resource was cloned.
apiResourceId Integer Read-only. A unique identifier for each resource.
apiResourceLogicId Integer Read-only. A unique identifier of the same cloned resource across endpoint versions.
apiResourceMethods Resource.apiResourceMethods[n] Encapsulates information about the HTTP methods to which each resource may respond.
apiResourceName String A name for the resource.
createDate String Read-only. An ISO–6801 timestamp string indicating when you initially created the resource.
createdBy String Identifies who initially created the resource.
description String A description to clarify the resource’s function within the API.
link String The location of the navigable resource within this API, for use by API clients. See Hypermedia for details.
lockVersion Number Read-only. An identifier used for optimistic locking. See Concurrency Control for details.
resourcePath String The URL template pattern, relative to the API’s basePath, to which this resource responds.
updateDate String Read-only. An ISO–6801 timestamp string indicating when you most recently modifies the resource.
updatedBy String Identifies who last modified the resource.

Resource.apiResourceMethods[n]  

Encapsulates information about the HTTP methods to which each resource may respond.

Member Type Required Description
apiResourceMethod Enumeration The core HTTP method to which this resource may respond, either get, put, post, delete, head, patch, or options.
apiResourceMethodId Integer Read-only. A unique identifier generated for each resource’s allowed method.

CacheSettings

This object provides a configuration for caching an endpoint. Caching settings specify properties such as the maximum age of content in the cache, caching HTTP error responses, and downstream cacheability for API clients

Sample GET:

{
    "enabled": true,
    "option": "CACHE",
    "maxAge": {
        "duration": 123,
        "unit": "SECONDS"
    },
    "serveStale": false,
    "downstreamCaching": {
        "option": "NOT_ALLOW_CACHING",
        "lifetime": "SMALLER_VALUE",
        "maxAge": null,
        "headers": "CACHE_CONTROL_AND_EXPIRES",
        "markAsPrivate": false
    },
    "errorCaching": {
        "enabled": false,
        "maxAge": null,
        "preserveStale": false
    },
    "resources": {
        "12083": {
            "path": "/1",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "PUT"
            ],
            "option": "CACHE",
            "maxAge": {
                "duration": 123,
                "unit": "SECONDS"
            },
            "serveStale": false
        },
        "12084": {
            "path": "/2",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "OPTIONS",
                "PUT",
                "PATCH"
            ],
            "option": "BYPASS_CACHE",
            "maxAge": null,
            "serveStale": false
        }
    }
}

CacheSettings Members

Member Type Required Description
downstreamCaching CacheSettings.downstreamCaching Downstream caching settings.
enabled Boolean Enables or disables all caching functionality.
errorCaching CacheSettings.errorCaching Error caching settings.
maxAge CacheSettings.resources.maxAge Maximum age of content in cache.
option Enumeration Options for how to pass cached content, either CACHE, BYPASS_CACHE, NO_STORE, HONOR_ORIGIN_CACHE_CONTROL, HONOR_ORIGIN_EXPIRES, or HONOR_ORIGIN_CACHE_CONTROL_AND_EXPIRES.
resources CacheSettings.resources The map of ID resource to settings
serveStale Boolean Serves a stale response in case origin cannot be contacted

CacheSettings.downstreamCaching  

Downstream caching settings.

Member Type Required Description
headers Enumeration Lifetime policy, either CACHE_CONTROL_AND_EXPIRES - Send both Cache-control and Expires, CACHE_CONTROL - Send only Cache-control, EXPIRES - Send only Expires, or SAME_AS_ORIGIN - send same headers as origin.
lifetime Enumeration Lifetime policy, either SMALLER_VALUE - Smaller value: origin header or remaining edge TTL, GREATER_VALUE - Greater value: origin header or remaining edge TTL, REMAINING_EDGE_TTL - Remaining edge TTL, FULL_EDGE_TTL - Full edge TTL (max-age), FIXED_VALUE - Fixed Value, or CALCULATES_EXPIRES_FROM_ORIGIN_CACHE_CONTROL - Calculate Expires from origin Cache-Control.
markAsPrivate Boolean Indicates not to store the response with a shared cache. This is useful when you want to set a maximum age for the end client, but have shared caches not store the response.
maxAge CacheSettings.resources.maxAge Maximum age of content in cache.
option Enumeration Option for downstream caching, either ALLOW_CACHING - Allow Caching, ALLOW_CACHING_REQUIRES_REVALIDATION - allow caching, require revalidation (no cache), NOT_ALLOW_CACHING - don’t allow caching (bust), PASS_CACHEABILITY_HEADERS_FROM_ORIGIN - pass cacheability headers from origin, or DO_NOT_SEND_HEADERS - don’t send headers, apply browser defaults.

CacheSettings.downstreamCaching.maxAge  

Maximum age of content in cache.

Member Type Required Description
duration Integer Duration in selected unit of time.
unit Enumeration Unit of time, either DAYS, HOURS, MINUTES, or SECONDS.

CacheSettings.errorCaching  

Error caching settings.

Member Type Required Description
maxAge CacheSettings.resources.maxAge Maximum age of content in cache.
preserveStale Boolean Preserves a stale response in case origin cannot be contacted.

CacheSettings.errorCaching.maxAge  

Maximum age of content in cache.

Member Type Required Description
duration Integer Duration in selected unit of time.
unit Enumeration Unit of time, either DAYS, HOURS, MINUTES, or SECONDS.

CacheSettings.maxAge  

Maximum age of content in cache.

Member Type Required Description
duration Integer Duration in selected unit of time.
unit Enumeration Unit of time, either DAYS, HOURS, MINUTES, or SECONDS.

CacheSettings.resources  

The map of ID resource to settings

Member Type Required Description
maxAge CacheSettings.resources.maxAge Maximum age of content in cache.
option Enumeration Resource caching option, either CACHE, NO_STORE, BYPASS_CACHE, HONOR_ORIGIN_CACHE_CONTROL, HONOR_ORIGIN_CACHE_CONTROL_AND_EXPIRES, or HONOR_ORIGIN_EXPIRES.
serveStale Boolean Serve stale objects on origin error.

CacheSettings.resources.maxAge  

Maximum age of content in cache.

Member Type Required Description
duration Integer Duration in selected unit of time.
unit Enumeration Unit of time, either DAYS, HOURS, MINUTES, or SECONDS.

CacheSettings.resources.{[0–9]{1,}}  

API privacy settings for the endpoint

Member Type Required Description
enabled Boolean Enable or disable settings for this resource.
methods Enumeration Methods used for these settings, either POST, GET, PUT, DELETE, HEAD, OPTIONS, or PATCH.
path String The path to the resource.

ApiPrivacySettings

API Privacy settings

Sample GET:

{
    "resources": {
        "6362": {
            "path": "/add",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "OPTIONS",
                "PUT",
                "PATCH"
            ],
            "notes": "Public resource with all methods",
            "public": true
        }
    },
    "private": true
}

ApiPrivacySettings Members

Member Type Required Description
private Boolean Indicates whether the endpoint should be private.
resources ApiPrivacySettings.resources Resources with API privacy settings.

ApiPrivacySettings.resources.{[0–9]{1,}}  

API privacy settings for the endpoint

Member Type Required Description
methods Array Read-only. A list of methods available for this resource.
notes String Read-only. Notes about this resource.
path String the path to the resource.
public Boolean Indicates whether the endpoint should be public.

Gzip

This object provides a configuration for GZIP compression functionality. This ensures proper compression of content-types for bandwidth savings

Sample GET:

{
    "compressResponse": "ALWAYS"
}

Gzip Members

Member Type Required Description
compressResponse Enumeration Enable or disable the Gzip functionality. ALWAYS allows compressed responses without restrictions, NEVER forbids compressed responses, and SAME_AS_ORIGIN allows compressed responses as specified on the origin server.

Cors

This object provides a configuration for cross-origin resource sharing (CORS) for an endpoint. CORS enables user agents to request restricted resources from external domains outside the domain that served the first resource

Sample GET:

{
    "enabled": true,
    "allowedOrigins": [
        "*"
    ],
    "allowedHeaders": [
        "Akamai-Cors-Allowed"
    ],
    "allowedMethods": [
        "GET"
    ],
    "allowCredentials": false,
    "exposedHeaders": [
        "Akamai-Cors-Exposed"
    ],
    "preflightMaxAge": 86400
}

Cors Members

Member Type Required Description
allowCredentials Boolean Indicates whether the response to the request can be exposed to the page.
allowedHeaders Array Specifies the HTTP headers you can use when making the actual request through the Access-Control-Allow-Headers header.
allowedMethods Array Specifies the method or methods allowed when you access the resource through the Access-Control-Allow-Methods header.
allowedOrigins Array Content from specified origins can refer to / to reference this registered API. * means all hostnames.
enabled Boolean Enables or disables all CORS functionality.
exposedHeaders Array A whitelist of headers that browsers can access.

Jwt

This object provides a configuration for JSON Web Token (JWT) validation for an endpoint. JWT is an open standard (RFC 7519) that defines a compact and self-contained method for securely transmitting information between parties encoded as a JSON object. It is often used for authentication purposes.

Sample GET:

{
    "enabled": true,
    "settings": {
        "location": "COOKIE",
        "paramName": "cookieWT",
        "clockSkew": 0,
        "validation": {
            "claims": [
                {
                    "name": "aud",
                    "validate": true,
                    "required": false,
                    "value": [
                        "ala"
                    ],
                    "type": "ARRAY"
                },
                {
                    "name": "iss",
                    "validate": true,
                    "required": true,
                    "value": "kot",
                    "type": "STRING"
                },
                {
                    "name": "sub",
                    "validate": true,
                    "required": false,
                    "value": "kozak",
                    "type": "STRING"
                },
                {
                    "name": "exp",
                    "validate": false,
                    "required": false,
                    "value": null,
                    "type": "TIMESTAMP"
                },
                {
                    "name": "nbf",
                    "validate": false,
                    "required": false,
                    "value": null,
                    "type": "TIMESTAMP"
                }
            ],
            "rsaPublicKeyA": {
                "name": "id_rsa-2.pub",
                "content": "-----BEGIN PUBLIC KEY-----\nMIIBIjwE9GQg+OR0WYHtq4AKsvK2eucDs06ejWRDb+uDN\n80jxZCxfweelZKvYT9Qdms/1SJv\nrQIDAQAB\n-----END PUBLIC KEY-----\n"
            },
            "rsaPublicKeyB": null
        }
    },
    "resources": {
        "11904": {
            "enabled": true,
            "path": "/endpoint1",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "OPTIONS",
                "PUT",
                "PATCH"
            ],
            "notes": null
        },
        "11903": {
            "enabled": false,
            "path": "/endpoint2",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "OPTIONS",
                "PUT",
                "PATCH"
            ],
            "notes": null
        }
    }
}

Jwt Members

Member Type Required Description
enabled Boolean Enables or disables all JWT functionality.
resources Jwt.resources The map of ID resource to settings
settings Jwt.settings Settings for JWT.

Jwt.resources  

The map of ID resource to settings

Member Type Required Description
notes String Notes.

Jwt.resources.{[0–9]{1,}}  

API privacy settings for the endpoint

Member Type Required Description
enabled Boolean Enable or disable settings for this resource.
methods Enumeration Methods used for these settings, either POST, GET, PUT, DELETE, HEAD, OPTIONS, or PATCH.
path String The path to the resource.

Jwt.settings  

Settings for JWT.

Member Type Required Description
clockSkew Integer The number of seconds you want to allow for flexibility in the determination of the expiration time for a JWT.
location Enumeration The location in the request where the token resides, either the HEADER, COOKIE, or QUERY parameter name.
paramName String The header, cookie, or query parameter name, based on location.
validation Jwt.settings.validation You can specify specific JWT reserved claims that you want to verify at the edge, and exempt individual resources from requiring validation.

Jwt.settings.validation  

You can specify specific JWT reserved claims that you want to verify at the edge, and exempt individual resources from requiring validation.

Member Type Required Description
claims Jwt.settings.validation.claims[n] Backup RSA key for a JWT.
rsaPublicKeyA Jwt.settings.validation.rsaPublicKeyA RSA key for a JWT.
rsaPublicKeyB Jwt.settings.validation.rsaPublicKeyB The RSA key for a JWT.

Jwt.settings.validation.claims[n]  

Backup RSA key for a JWT.

Member Type Required Description
name Enumeration The name of the reserved claim. Specify aud to identify the audience that the JWT is intended for, iss to identify the issuer of the JWT claim, sub to identify the subject of the JWT, exp to identify the expiration time on or after which the token is not accepted for processing, or nbf to identify the time before which the token is not accepted for processing.
required Boolean Enables or disables the required existence of this claim.
type Enumeration The type of data of the value, either ARRAY, STRING, or TIMESTAMP.
validate Boolean Enables or disables this validation.
value Array Values of the claim.
value String Value of the claim.

Jwt.settings.validation.rsaPublicKeyA  

RSA key for a JWT.

Member Type Required Description
content String The content of the file with an RSA key.
name String The name of the file with an RSA key.

Jwt.settings.validation.rsaPublicKeyB  

The RSA key for a JWT.

Member Type Required Description
content String The content of the file with an RSA key.
name String The name of the file with an RSA key.

Last modified: 11/22/2017