API Endpoint Definition API v1 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, it either must be provided in request objects, or is always present in response objects:

Member is required 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.

Schemas

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 Endpoint Array 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.

Endpoint

Encapsulates an endpoint.

Sample GET:

{
    "securityScheme": {
        "securitySchemeId": 12345,
        "securitySchemeDetail": {
            "apiKeyLocation": "query",
            "apiKeyName": "calculate_name"
        },
        "securitySchemeDescription": "api key for security",
        "securitySchemeType": "apikey"
    },
    "apiEndPointName": "Membership Benefits",
    "apiEndPointScheme": "https",
    "description": "Provides information about membership benefits and available services.",
    "apiEndPointId": 1234,
    "apiCategoryIds": [
        123,
        125
    ],
    "basePath": "/api/v1",
    "apiResourceBaseInfo": [
        {
            "description": "resource description",
            "apiResourceName": "cloud security",
            "resourcePath": "/resources/{resourceId}",
            "link": "/api-definitions/v1/endpoints/1234/resources/7689",
            "updateDate": "2013-10-07T17:41:52+0000",
            "createdBy": "rsajj@akamai.com",
            "updatedBy": "yauoid",
            "createDate": "2013-10-07T17:41:52+0000",
            "apiResourceId": 7689
        },
        {
            "description": "resource description",
            "apiResourceName": "cloud security",
            "resourcePath": "/resources/{resourceId}/hosts",
            "link": "/api-definitions/v1/endpoints/1234/resources/7690",
            "updateDate": "2013-10-07T17:41:52+0000",
            "createdBy": "rsajj@akamai.com",
            "updatedBy": "yauoid",
            "createDate": "2013-10-07T17:41:52+0000",
            "apiResourceId": 7690
        }
    ],
    "akamaiSecurityRestrictions": {
        "MAX_DOC_DEPTH": 30,
        "MAX_JSONXML_ELEMENT": 12134,
        "MAX_BODY_SIZE": 9910801,
        "MAX_INTEGER_VALUE": 12898979,
        "MAX_STRING_LENGTH": 123,
        "MAX_ELEMENT_NAME_LENGTH": 1234,
        "POSTIVE_SECURITY_ENABLED": 1
    },
    "createDate": "2013-10-07T17:41:52+0000",
    "updateDate": "2013-10-07T17:41:52+0000",
    "createdBy": "rafda@akamai.com",
    "updatedBy": "yauoid",
    "apiEndPointHosts": [
        "www.akamai.com",
        "www3.akamai.com"
    ],
    "consumeType": "json",
    "lockVersion": 18298372979,
    "groupId": 67890,
    "contractId": "1-xc789"
}

Endpoint Members  

Member Type Required Description
akamaiSecurityRestrictions Endpoint.akamaiSecurityRestrictions Collects various restrictions to apply to the endpoint.
apiCategoryIds Array A list of Category identifiers that apply to this endpoint. Value may be null rather than an empty array for uncategorized endpoints.
apiEndPointHosts Array A list of hostname strings that may receive traffic for this API. Value may be null rather than an empty array for disabled APIs.
apiEndPointId Integer Read-only. Unique identifier for each endpoint.
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.
apiResourceBaseInfo Resource Array Encapsulates each Resource the API endpoint supports.
basePath String The URL path that serves as a root prefix for all resources’ resourcePath values, / if empty. Do not append a / character to the path.
consumeType Enumeration The content type the endpoint exchanges, either json, xml, json/xml for dual-format APIs, any, or none.
contractId String Read-only. Unique identifier for the contract with Akamai under which security for this API is provisioned.
createDate String Read-only. 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. 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.
securityScheme Endpoint.securityScheme Encapsulates information about the key with which users may access the API.
updateDate String Read-only. ISO–6801 timestamp string indicating when the endpoint was most recently modified.
updatedBy String Identifies who last modified the endpoint.

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.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. 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
apiKeyLocation Enumeration Identifies from where to extract the apiKeyName value, either a header or a query parameter.
apiKeyName String The name of the header or query parameter that serves as the API key.

Resource

Encapsulates each Resource the API endpoint supports.

Sample GET:

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

Resource Members  

Member Type Required Description
apiResourceId Integer Read-only. Unique identifier for each resource.
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. 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. ISO–6801 timestamp string indicating when the resource was most recently modified.
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.

Category

This object encapsulates a category of APIs.

Sample GET:

{
    "apiCategoryDescription": "web media delivery apis",
    "apiCategoryName": "Media Delivery",
    "lockVersion": 139793907,
    "apiCategoryId": 13,
    "link": "/api-definitions/v1/categories/13",
    "updateDate": "2013-10-07T17:41:52+0000",
    "createdBy": "rdslj@akamai.com",
    "updatedBy": "rajdj@akamai.com",
    "createDate": "2013-10-07T17:41:52+0000"
}

Category Members  

Member Type Required Description
apiCategoryDescription String A description of the category, which may help tag related APIs.
apiCategoryId Integer Read-only. Unique identifier for each category.
apiCategoryName String The name of the category, which needs to be unique per account. Writing an empty value reflects back as an __UNCATEGORIZED__ keyword.
createDate String Read-only. ISO–6801 timestamp string indicating when the category was initially created.
createdBy String Identifies who initially created the category.
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.
updateDate String Read-only. ISO–6801 timestamp string indicating when the category was most recently modified.
updatedBy String Identifies who last modified the category.
usageCount Integer The number of endpoints that share this category.

Method

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

Method Members  

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.

AcgPair

Encapsulates a pairing of contract and group under which to provision security for an API endpoint.

Sample GET:

[
    {
        "contractId": "3-1Cgoa",
        "displayName": "xxxx-3-1Cgoa - 3-1Cgoa",
        "acgId": "3-1Cgoa",
        "groupId": 58220
    },
    {
        "contractId": "3-1Cgoa",
        "displayName": "Dev Team - 3-1Cgoa",
        "acgId": "3-1Cgoa.G75683",
        "groupId": 75683
    }
]

AcgPair Members  

Member Type Required Description
acgId String Unique identifier for each pairing of contract and group.
contractId String Unique identifier for the Akamai contract within the pairing.
displayName String A descriptive name for the pairing of contract and group.
groupId Number Unique identifier for the group within the pairing.

Last modified: 3/22/2017