API Endpoint Definition API v1

The original version of the API Endpoint Definition API associates API endpoints with a Kona Site Defender configuration to monitor security issues.

Learn more:

Overview

The API Endpoint Definition API lets you programmatically define a new API endpoint or update the definition of an existing API endpoint on Akamai.

Who should use this API

You can use this API if you need to programmatically define a new API endpoint or update the definition of an existing API endpoint on the Akamai platform. Note that this API does not modify any Kona Site Defender firewall policies that protect your API endpoints, but is a prerequisite to apply security (You use this API to define your API endpoint in order to configure protections for it).

You would typically deploy API traffic over the Akamai network on a pass-through basis, with your database requests bypassing the cache and going directly to your origin. Using Property Manager (or PAPI), you might even deploy a set of custom API hostnames for your customers.

This API lets you specify your API endpoints by hostname and base path, identify the set of expected URL resources and operations, and define the size and shape of the exchanged data objects. Use this API before your security team applies a Kona Site Defender firewall policy to your API endpoints.

This API’s programmatic interface offers an alternative to Akamai Control Center, where the same capabilities are available under the Configure ⇒ Manage API Definitions menu. Use this API to enable batch deployment for your own security-enabled APIs.

Getting started

Before using this API for the first time:

  • Review Get Started for API tools that Akamai provides.

  • Review Authorize Your Client to create your API access credentials and authorizations. As detailed in The API Identity Model, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

Concurrency control

If more than one Endpoints API client accesses the same data at the same time, a simple locking mechanism prevents them from overwriting each other’s data. When you GET an object such as an endpoint, resource, or category, the object features a lockVersion member that represents a time stamp of its most recent modification. When you modify and PUT back the object, the request fails if the lockVersion no longer matches that of the stored version of the object, which updates when someone else modifies the data. In that case, repeat the process of reading, modifying, and writing the object back.

Hypermedia

This API provides a pair of hypermedia mechanisms to guide client applications to navigate among available data. In any JSON object, a link member indicates the URL where the data is located, expressed as a server path with no hostname.

When performing operations to list collections of objects, you can retrieve the ID value of the relevant object to form a new request URL to select it, or simply make a call directly to the link URL. This example shows condensed data:

[
    {
        "apiResourceId": 123,
        "apiResourceName": "cloud security",
        "link": "/api-definitions/v1/endpoints/111/resources/123",
        "resourcePath": "/resources/security/{resourceId}"
    },
    {
        "apiResourceId": 125,
        "apiResourceName": "cloud security image",
        "link": "/api-definitions/v1/endpoints/111/resources/125",
        "resourcePath": "/resources/security-image/{resourceId}"
    }
]

When using pagination parameters to list endpoints, links hypermedia members also provide navigation href links to next and previous pages. The self link relation provides a link to the current set of results:

{
    "apiEndPoints": [
        { "apiEndPointId": 1234 },
        { "apiEndPointId": 1235 }
    ],
    "links": [
        {
            "href": "/api-definitions/v1/endpoints?pageSize=2&page=0",
            "rel": "previous"
        },
        {
            "href": "/api-definitions/v1/endpoints?pageSize=2&page=1",
            "rel": "self"
        },
        {
            "href": "/api-definitions/v1/endpoints?pageSize=2&page=2",
            "rel": "next"
        }
    ],
    "page": 8,
    "pageSize": 2,
    "totalSize": 15
}

Resources

The API Endpoint Definition API allows you to programmatically define an API endpoint and its set of component resources. This API allows you to define request body and resource constraints so that you can enforce them separately as a whitelist in a Kona Site Defender firewall policy.

The following summarizes the objects with which you interact:

  • An endpoint is a set of logically related API resources. See the Endpoint object.

  • A resource is a URL pattern that responds to HTTP method calls for each API operation. See the Resource object.

  • You can assign any number of overlapping categories to each endpoint. See the Category object.

  • You provision API endpoint services under an Akamai contract, and also assign a Control Center portal group. The AcgPair object encapsulates this pairing of information.

NOTE: In the table below and for all other Akamai APIs, responsive URL patterns are commonly referred to as endpoints, not as resources as in this API. Within this API, an endpoint refers to a logical collection of resources.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Endpoints  
List Endpoints GET /api-definitions/v1/endpoints{?category,contains,contractId,groupId,page,pageSize,sortBy,sortOrder}
Create a New Endpoint POST /api-definitions/v1/endpoints
Create a New API Endpoint from a File Upload POST /api-definitions/v1/endpoints/files
Get an Endpoint GET /api-definitions/v1/endpoints/{apiEndPointId}
Modify an Endpoint PUT /api-definitions/v1/endpoints/{apiEndPointId}
Remove an Endpoint DELETE /api-definitions/v1/endpoints/{apiEndPointId}
Upload a File to Replace an Endpoint’s Resources POST /api-definitions/v1/endpoints/{apiEndPointId}/file
List Resources GET /api-definitions/v1/endpoints/{apiEndPointId}/resources
Create a New Resource POST /api-definitions/v1/endpoints/{apiEndPointId}/resources
Get a Resource GET /api-definitions/v1/endpoints/{apiEndPointId}/resources/{apiResourceId}
Modify a Resource PUT /api-definitions/v1/endpoints/{apiEndPointId}/resources/{apiResourceId}
Remove a Resource DELETE /api-definitions/v1/endpoints/{apiEndPointId}/resources/{apiResourceId}
Categories  
List Categories GET /api-definitions/v1/categories{?withUsageInfo}
Create a New Category POST /api-definitions/v1/categories
Get a Category GET /api-definitions/v1/categories/{apiCategoryId}
Modify a Category PUT /api-definitions/v1/categories/{apiCategoryId}
Remove a Category DELETE /api-definitions/v1/categories/{apiCategoryId}
Contracts  
List Contracts and Groups GET /api-definitions/v1/contracts/groups
List Hostnames GET /api-definitions/v1/contracts/{contractId}/groups/{groupId}/hosts

List endpoints

Lists available API endpoints, with results optionally paginated, sorted, and filtered. If no APIs are available, the operation responds with an empty array.

GET /api-definitions/v1/endpoints{?category,contains,contractId,groupId,page,pageSize,sortBy,sortOrder}

Sample: /api-definitions/v1/endpoints?category=Site%20Delivery&contains=cloud%20security&contractId=1-xc789&groupId=67890&page=5&pageSize=50&sortBy=updateDate&sortOrder=asc

Parameter Type Sample Description
Optional query parameters
category String Site Delivery Filters endpoints by the specified apiCategoryName, including the __UNCATEGORIZED__ keyword.
contains String cloud security Search query substring criteria matching the API’s name, description, basePath, apiCategoryName, and resourcePath.
contractId String 1-xc789 Filter to a specific contract. You need to specify this along with a groupId.
groupId Integer 67890 Filter to a specific group. You need to specify this along with a contractId.
page Integer 5 The page number index, starting at the default value of 1.
pageSize Integer 50 The number of API endpoints on each page of results, 25 by default.
sortBy Enumeration updateDate The field to sort by, either the API name (corresponding to the apiEndPointName member) or updateDate.
sortOrder Enumeration asc Sort order, either desc for descending or the default asc for ascending.

Status 200 application/json

Response Body:

{
    "totalSize": 15,
    "pageSize": 2,
    "links": [
        {
            "href": "/api-definitions/v1/endpoints?pageSize=2&page=1",
            "rel": "self"
        },
        {
            "href": "/api-definitions/v1/endpoints?pageSize=2&page=2",
            "rel": "next"
        },
        {
            "href": "/api-definitions/v1/endpoints?pageSize=2&page=0",
            "rel": "previous"
        }
    ],
    "apiEndPoints": [
        {
            "apiEndPointId": 1234,
            "apiEndPointScheme": "https",
            "description": "Provides information about membership benefits and available services.",
            "apiEndPointName": "Membership Benefits",
            "lockVersion": 179389174,
            "createDate": "2013-10-07T17:41:52+0000",
            "apiResourceBaseInfo": [
                {
                    "description": "resource description",
                    "lockVersion": 179389174,
                    "apiResourceName": "cloud security",
                    "resourcePath": "/resources/{resourceId}",
                    "link": "/api-definitions/v1/endpoints/1234/resources/7689",
                    "updateDate": "2013-10-07T17:41:52+0000",
                    "createdBy": "rsingama@akamai.com",
                    "updatedBy": "yauoid",
                    "createDate": "2013-10-07T17:41:52+0000",
                    "apiResourceId": 7689
                }
            ],
            "apiCategoryIds": [
                123,
                125
            ],
            "updateDate": "2015-10-07T17:41:52+0000",
            "createdBy": "rsahk",
            "updatedBy": "rsahk",
            "apiEndPointHosts": [
                "api-stage.abc.com",
                "api.abc.com"
            ],
            "basePath": "/api/v1"
        },
        {
            "apiEndPointId": 1235,
            "apiEndPointScheme": "https",
            "description": "Provides information about membership benefits and available services.",
            "apiEndPointName": "Membership Benefits",
            "lockVersion": 179389174,
            "createDate": "2013-10-07T17:41:52+0000",
            "apiResourceBaseInfo": [
                {
                    "description": "resource description",
                    "lockVersion": 179389174,
                    "apiResourceName": "cloud security",
                    "resourcePath": "/resources/{resourceId}/hosts",
                    "link": "/api-definitions/v1/endpoints/1235/resources/7690",
                    "updateDate": "2013-10-07T17:41:52+0000",
                    "createdBy": "rsajj",
                    "updatedBy": "yauoid",
                    "createDate": "2013-10-07T17:41:52+0000",
                    "apiResourceId": 7690
                }
            ],
            "apiCategoryIds": [
                123,
                125
            ],
            "updateDate": "2015-10-07T17:41:52+0000",
            "createdBy": "rsahk",
            "updatedBy": "rsahk",
            "apiEndPointHosts": [
                "api-stage.abc.com",
                "api.abc.com"
            ],
            "basePath": "/api/v1"
        }
    ],
    "page": 8
}

  1. Optionally set the contractId and groupId query parameters to filter results provisioned under a specific pairing of contract and group.

  2. Optionally filter results to a specific category, or set contains to search on text.

  3. If you want to affect how output sorts, set the sortBy query parameter to either name or updateDate, or set sortOrder to asc or desc.

  4. If you want to modify pagination, set the pageSize query parameter for the number of records per page, and the overall page number.

  5. Make a GET request to /api-definitions/v1/endpoints{?page,pageSize,category,contains,sortBy,sortOrder,contractId,groupId}.

  6. Optionally follow the hypermedia links to navigate to the next or previous page in the paginated results.

The response’s apiEndPoints array features Endpoint objects from which you typically extract an apiEndPointId to access specific endpoints.

Create a new endpoint

Creates an empty new API endpoint service with no resources. The endpoint’s name needs to be unique within the account.

POST /api-definitions/v1/endpoints

Content-Type: application/json

Request Body:

{
    "securityScheme": {
        "securitySchemeId": null,
        "securitySchemeDetail": {
            "apiKeyName": "calculate_name",
            "apiKeyLocation": "query"
        },
        "securitySchemeDescription": "api key for security",
        "securitySchemeType": "apikey"
    },
    "apiEndPointScheme": "https",
    "description": "Provides information about membership benefits and available services.",
    "apiEndPointHosts": [
        "www.akamai.com",
        "www3.akamai.com"
    ],
    "apiEndPointId": null,
    "apiCategoryIds": [
        123,
        125
    ],
    "basePath": "/api/v1",
    "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
    },
    "apiEndPointName": "Membership Benefits",
    "consumeType": "json",
    "groupId": 67890,
    "contractId": "1-xc789"
}

Status 201 application/json

Headers:

Location: /api-definitions/v1/endpoints/123

Response Body:

{
    "securityScheme": {
        "securitySchemeId": 12345,
        "securitySchemeDetail": {
            "apiKeyName": "calculate_name",
            "apiKeyLocation": "query"
        },
        "securitySchemeDescription": "api key for security",
        "securitySchemeType": "apikey"
    },
    "apiEndPointScheme": "https",
    "description": "Provides information about membership benefits and available services.",
    "apiEndPointHosts": [
        "www.akamai.com",
        "www3.akamai.com"
    ],
    "apiEndPointId": 1234,
    "apiCategoryIds": [
        123,
        125
    ],
    "basePath": "/api/v1",
    "groupId": 67890,
    "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
    },
    "updateDate": "2013-10-07T17:41:52+0000",
    "createdBy": "rafda@akamai.com",
    "updatedBy": "yauoid",
    "apiEndPointName": "Membership Benefits",
    "consumeType": "json",
    "lockVersion": 18298372979,
    "createDate": "2013-10-07T17:41:52+0000",
    "contractId": "1-xc789"
}

  1. Run the List Contracts and Groups operation.

  2. From the response array, choose the appropriate pairing of contract and group under which you want to provision the new API service. Store the contractId and groupId values.

  3. Optionally run the List Categories operation and store apiCategoryId from the array of Category objects.

  4. Build an Endpoint object, specifying the contractId and groupId members, and a unique apiEndPointName.

  5. POST the object to /api-definitions/v1/endpoints.

The response reflects back the complete Endpoint object, from which you can store the apiEndPointId.

Create a new API endpoint from a file upload

Create a new endpoint and set of resources based on an uploaded API descriptor file or URL link.

POST /api-definitions/v1/endpoints/files

Content-Type: multipart/form-data

See Parameters for details on upload content.

Parameter Type Sample Description
Form parameters
importFileFormat Enumeration raml The format of the API descriptor, either raml (0.8) or swagger (2.0).
importFile File #%RAML 0.8... The complete file to import.
importUrl String https://example.com/descriptor.raml The URL from which to retrieve the API descriptor file.
root String api_descriptor.raml If the import file is a ZIP archive, This identifies the API descriptor’s filename within the archive.
contractId String 3-1Cgoa Unique identifier for the contract under which to provision the endpoint.
groupId String 67890 Unique identifier for the group under which to provision the endpoint.

Status 201 application/json

Headers:

Location: /api-definitions/v1/endpoints/123

Response Body:

{
    "securityScheme": {
        "securitySchemeId": 12345,
        "securitySchemeDetail": {
            "apiKeyName": "calculate_name",
            "apiKeyLocation": "query"
        },
        "securitySchemeDescription": "api key for security",
        "securitySchemeType": "apikey"
    },
    "apiEndPointScheme": "https",
    "description": "Provides information about membership benefits and available services.",
    "apiEndPointHosts": [
        "www.akamai.com",
        "www3.akamai.com"
    ],
    "apiEndPointId": 1234,
    "apiCategoryIds": [
        123,
        125
    ],
    "basePath": "/api/v1",
    "groupId": 67890,
    "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
    },
    "updateDate": "2013-10-07T17:41:52+0000",
    "createdBy": "rafda@akamai.com",
    "updatedBy": "yauoid",
    "apiEndPointName": "Membership Benefits",
    "consumeType": "json",
    "lockVersion": 18298372979,
    "createDate": "2013-10-07T17:41:52+0000",
    "contractId": "1-xc789"
}

  1. Prepare an API descriptor file and set the importFileFormat to raml or swagger.

  2. Assign the filename as the importFile.

  3. Optionally embed the descriptor within a ZIP archive, in which case reset the descriptor filename as root and the name of the archive as importFile.

  4. Optionally make the descriptor or archive file available on the web at an importUrl.

  5. Run the List Contracts and Groups operation.

  6. From the response array, choose the appropriate pairing of contract and group under which you want to provision the new API service. Store the contractId and groupId values.

  7. Prepare a multipart/form-data request specifying the fields listed in Parameters. Specify either an importFile or importUrl, and make sure to specify the root if you are uploading a ZIP archive.

  8. Make a form data POST request to /api-definitions/v1/endpoints/files.

The response Endpoint reflects the newly created API and set of resources based on your descriptor file.

Get an endpoint

Gets information about a specific endpoint.

GET /api-definitions/v1/endpoints/{apiEndPointId}

Sample: /api-definitions/v1/endpoints/12892

Parameter Type Sample Description
URL parameters
apiEndPointId Integer 12892 Unique integer identifier for each API endpoint service.

Status 200 application/json

Response Body:

{
    "securityScheme": {
        "securitySchemeId": 12345,
        "securitySchemeDetail": {
            "apiKeyName": "calculate_name",
            "apiKeyLocation": "query"
        },
        "securitySchemeDescription": "api key for security",
        "securitySchemeType": "apikey"
    },
    "apiEndPointScheme": "https",
    "description": "Provides information about membership benefits and available services.",
    "apiEndPointHosts": [
        "www.akamai.com",
        "www3.akamai.com"
    ],
    "apiEndPointId": 1234,
    "apiCategoryIds": [
        123,
        125
    ],
    "basePath": "/api/v1",
    "groupId": 67890,
    "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
    },
    "updateDate": "2013-10-07T17:41:52+0000",
    "createdBy": "rafda@akamai.com",
    "updatedBy": "yauoid",
    "apiEndPointName": "Membership Benefits",
    "consumeType": "json",
    "lockVersion": 18298372979,
    "createDate": "2013-10-07T17:41:52+0000",
    "contractId": "1-xc789"
}

  1. If you don’t already have an apiEndPointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the apiEndPoints array and store its apiEndPointId.

  3. Make a GET request to /api-definitions/v1/endpoints/{apiEndPointId}.

The response is an Endpoint object.

Modify an endpoint

Update details about a specific endpoint.

PUT /api-definitions/v1/endpoints/{apiEndPointId}

Sample: /api-definitions/v1/endpoints/12892

Content-Type: application/json

Request Body:

{
    "securityScheme": {
        "securitySchemeId": 12345,
        "securitySchemeDetail": {
            "apiKeyName": "calculate_name",
            "apiKeyLocation": "query"
        },
        "securitySchemeDescription": "api key for security",
        "securitySchemeType": "apikey"
    },
    "apiEndPointScheme": "https",
    "description": "Provides information about membership benefits and available services.",
    "apiEndPointHosts": [
        "www.akamai.com",
        "www3.akamai.com"
    ],
    "apiEndPointId": 1234,
    "apiCategoryIds": [
        123,
        125
    ],
    "basePath": "/api/v1",
    "groupId": 67890,
    "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
    },
    "updateDate": "2013-10-07T17:41:52+0000",
    "createdBy": "rafda@akamai.com",
    "updatedBy": "yauoid",
    "apiEndPointName": "Membership Benefits",
    "consumeType": "json",
    "lockVersion": 18298372979,
    "createDate": "2013-10-07T17:41:52+0000",
    "contractId": "1-xc789"
}
Parameter Type Sample Description
URL parameters
apiEndPointId Integer 12892 Unique integer identifier for each API endpoint service.

Status 200 application/json

Response Body:

{
    "securityScheme": {
        "securitySchemeId": 12345,
        "securitySchemeDetail": {
            "apiKeyName": "calculate_name",
            "apiKeyLocation": "query"
        },
        "securitySchemeDescription": "api key for security",
        "securitySchemeType": "apikey"
    },
    "apiEndPointScheme": "https",
    "description": "Provides information about membership benefits and available services.",
    "apiEndPointHosts": [
        "www.akamai.com",
        "www3.akamai.com"
    ],
    "apiEndPointId": 1234,
    "apiCategoryIds": [
        123,
        125
    ],
    "basePath": "/api/v1",
    "groupId": 67890,
    "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
    },
    "updateDate": "2013-10-07T17:41:52+0000",
    "createdBy": "rafda@akamai.com",
    "updatedBy": "yauoid",
    "apiEndPointName": "Membership Benefits",
    "consumeType": "json",
    "lockVersion": 18298372979,
    "createDate": "2013-10-07T17:41:52+0000",
    "contractId": "1-xc789"
}

  1. If you don’t have a full representation of the object you want to modify, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the apiEndPoints array and store its apiEndPointId.

  3. Run the Get an Endpoint operation for the complete representation of the object.

  4. Modify the Endpoint object.

  5. PUT the object back to the same URL as the GET: /api-definitions/v1/endpoints/{apiEndPointId}.

A 200 response confirms success, and the response object reflects your modifications.

Remove an endpoint

Removes a specific API endpoint and all resources it contains.

DELETE /api-definitions/v1/endpoints/{apiEndPointId}

Sample: /api-definitions/v1/endpoints/12892

Parameter Type Sample Description
URL parameters
apiEndPointId Integer 12892 Unique integer identifier for each API endpoint service.

Status 204

  1. If you don’t already have an apiEndPointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the apiEndPoints array and store its apiEndPointId.

  3. Make a DELETE request to /api-definitions/v1/endpoints/{apiEndPointId}.

A 204 response confirms the Endpoint object has been deleted.

Upload a file to replace an endpoint’s resources

Replace an endpoint’s resources based on an uploaded API descriptor file or URL link to a descriptor. This retains the endpoint’s higher-level information such as name and ID, categories, security restrictions, and assigned hosts.

POST /api-definitions/v1/endpoints/{apiEndPointId}/file

Sample: /api-definitions/v1/endpoints/12892/file

Content-Type: multipart/form-data

See Parameters for details on upload content.

Parameter Type Sample Description
URL parameters
apiEndPointId Integer 12892 Unique integer identifier for each API endpoint service.
Form parameters
importFileFormat Enumeration raml The format of the API descriptor, either raml (0.8) or swagger (2.0).
importFile File #%RAML 0.8... The complete file to import.
importUrl String https://example.com/descriptor.raml The URL from which to retrieve the API descriptor file.
root String api_descriptor.raml If the import file is a ZIP archive, This identifies the API descriptor’s filename within the archive.
contractId String 3-1Cgoa Unique identifier for the contract under which to provision the endpoint.
groupId String 67890 Unique identifier for the group under which to provision the endpoint.

Status 200 application/json

Response Body:

{
    "securityScheme": {
        "securitySchemeId": 12345,
        "securitySchemeDetail": {
            "apiKeyName": "calculate_name",
            "apiKeyLocation": "query"
        },
        "securitySchemeDescription": "api key for security",
        "securitySchemeType": "apikey"
    },
    "apiEndPointScheme": "https",
    "description": "Provides information about membership benefits and available services.",
    "apiEndPointHosts": [
        "www.akamai.com",
        "www3.akamai.com"
    ],
    "apiEndPointId": 1234,
    "apiCategoryIds": [
        123,
        125
    ],
    "basePath": "/api/v1",
    "groupId": 67890,
    "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
    },
    "updateDate": "2013-10-07T17:41:52+0000",
    "createdBy": "rafda@akamai.com",
    "updatedBy": "yauoid",
    "apiEndPointName": "Membership Benefits",
    "consumeType": "json",
    "lockVersion": 18298372979,
    "createDate": "2013-10-07T17:41:52+0000",
    "contractId": "1-xc789"
}

  1. If you don’t already have an apiEndPointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the apiEndPoints array and store its apiEndPointId.

  3. Prepare an API descriptor file and set the importFileFormat to raml or swagger.

  4. Assign the filename as the importFile.

  5. Optionally embed the descriptor within a ZIP archive, in which case reset the descriptor filename as root and the name of the archive as importFile.

  6. Optionally make the descriptor or archive file available on the web at an importUrl.

  7. Run the List Contracts and Groups operation.

  8. From the response array, choose the appropriate pairing of contract and group under which you want to provision the new API service. Store the contractId and groupId values.

  9. Prepare a multipart/form-data request specifying the fields listed in Parameters. Specify either an importFile or importUrl, and make sure to specify the root if you are uploading a ZIP archive.

  10. Make a form data POST request to /api-definitions/v1/endpoints/{apiEndPointId}/file.

The response Endpoint reflects the API with the updated set of resources based on your descriptor file.

List resources

Lists all resources defined for a given API endpoint.

GET /api-definitions/v1/endpoints/{apiEndPointId}/resources

Sample: /api-definitions/v1/endpoints/12892/resources

Parameter Type Sample Description
URL parameters
apiEndPointId Integer 12892 Unique integer identifier for each API endpoint service.

Status 200 application/json

Response Body:

[
    {
        "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
    }
]

  1. If you don’t already have an apiEndPointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the apiEndPoints array and store its apiEndPointId.

  3. Make a GET request to /api-definitions/v1/endpoints/{apiEndPointId}/resources.

The response is an array of Resource objects.

Create a new resource

Create a new resource within an API endpoint service. The resource’s full URL (concatenated hostname, basePath, and resourcepath) needs to be unique within the account.

POST /api-definitions/v1/endpoints/{apiEndPointId}/resources

Sample: /api-definitions/v1/endpoints/12892/resources

Content-Type: application/json

Request Body:

[
    {
        "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
    }
]
Parameter Type Sample Description
URL parameters
apiEndPointId Integer 12892 Unique integer identifier for each API endpoint service.

Status 201 application/json

Headers:

Location: /api-definitions/v1/endpoints/123/resources/1234

Response Body:

[
    {
        "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
    }
]

  1. Run the List Endpoints operation.

  2. Pick the appropriate endpoint from the apiEndPoints array and store its apiEndPointId.

  3. Build a Resource object. The only initial requirements are for a resourcePath and an apiResourceName, which both need to be unique within the API endpoint service.

  4. POST the object to /api-definitions/v1/endpoints/{apiEndPointId}/resources.

The response reflects back the complete Resource object, from which you can store the generated apiResourceId.

Get a resource

Get a specific resource within an API endpoint service.

GET /api-definitions/v1/endpoints/{apiEndPointId}/resources/{apiResourceId}

Sample: /api-definitions/v1/endpoints/12892/resources/7689

Parameter Type Sample Description
URL parameters
apiEndPointId Integer 12892 Unique integer identifier for each API endpoint service.
apiResourceId Integer 7689 Unique integer identifier for each API resource.

Status 200 application/json

Response Body:

[
    {
        "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
    }
]

  1. If you don’t already have an apiEndPointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the apiEndPoints array and store its apiEndPointId.

  3. If you don’t already have an apiResourceId value, run the List Resources operation.

  4. From the response array, choose the appropriate object and store its apiResourceId.

  5. Make a GET request to /api-definitions/v1/endpoints/{apiEndPointId}/resources/{apiResourceId}.

The response is a Resource object.

Modify a resource

Modify a specific resource within an API endpoint service.

PUT /api-definitions/v1/endpoints/{apiEndPointId}/resources/{apiResourceId}

Sample: /api-definitions/v1/endpoints/12892/resources/7689

Content-Type: application/json

Request Body:

[
    {
        "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
    }
]
Parameter Type Sample Description
URL parameters
apiEndPointId Integer 12892 Unique integer identifier for each API endpoint service.
apiResourceId Integer 7689 Unique integer identifier for each API resource.

Status 200 application/json

Response Body:

[
    {
        "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
    }
]

  1. If you don’t have a full representation of the object you want to modify, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the apiEndPoints array and store its apiEndPointId.

  3. Run the List Resources operation.

  4. From the response array, choose the appropriate object and store its apiResourceId.

  5. Run the Get a Resource operation for the full representation of the object.

  6. Modify the Resource object.

  7. PUT the object back to the same URL as the GET: /api-definitions/v1/endpoints/{apiEndPointId}/resources/{apiResourceId}.

A 200 response confirms success, and the response object reflects your modifications.

Remove a resource

Remove a resource from within an API endpoint service.

DELETE /api-definitions/v1/endpoints/{apiEndPointId}/resources/{apiResourceId}

Sample: /api-definitions/v1/endpoints/12892/resources/7689

Parameter Type Sample Description
URL parameters
apiEndPointId Integer 12892 Unique integer identifier for each API endpoint service.
apiResourceId Integer 7689 Unique integer identifier for each API resource.

Status 204

  1. If you don’t already have an apiEndPointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the apiEndPoints array and store its apiEndPointId.

  3. If you don’t already have an apiResourceId value, run the List Resources operation.

  4. From the response array, choose the appropriate object and store its apiResourceId.

  5. Make a DELETE request to /api-definitions/v1/endpoints/{apiEndPointId}/resources/{apiResourceId}.

A 204 response confirms the Resource object has been deleted.

List categories

List all categories available to assign to API endpoints, and optionally indicate the number of APIs tagged under each category.

GET /api-definitions/v1/categories{?withUsageInfo}

Sample: /api-definitions/v1/categories?withUsageInfo=true

Parameter Type Sample Description
Optional query parameters
withUsageInfo Boolean true When enabled, the response includes usageCount data indicating the number of APIs under the category, false by default.

Status 200 application/json

Response Body:

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

  1. Optionally set the withUsageInfo query parameter to true if you want listed categories to show the number of APIs they apply to.

  2. Make a GET request to /api-definitions/v1/categories{?withUsageInfo}.

The response is an array of Category objects.

Create a new category

Create a new category with which to tag API endpoints. The request’s apiCategoryName needs to be unique per account.

POST /api-definitions/v1/categories

Content-Type: application/json

Request Body:

{
    "apiCategoryDescription": "web performance apis",
    "apiCategoryName": "Web Performance"
}

Status 201 application/json

Headers:

Location: /api-definitions/v1/api-categories/123

Response Body:

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

  1. Build a Category object. The only initially required member is a unique apiCategoryName.

  2. POST the object to /api-definitions/v1/categories.

The response contains the complete Category object, from which you can store the generated apiCategoryId.

Get a category

Get a specific category used to tag API endpoints.

GET /api-definitions/v1/categories/{apiCategoryId}

Sample: /api-definitions/v1/categories/13

Parameter Type Sample Description
URL parameters
apiCategoryId Integer 13 Unique integer identifier for each category.

Status 200 application/json

Response Body:

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

  1. Run the List Categories operation.

  2. Choose the appropriate object from the response array and store its apiCategoryId.

  3. Make a GET request to /api-definitions/v1/categories/{apiCategoryId}.

The response is a Category object.

Modify a category

Update a category’s description or unique name.

PUT /api-definitions/v1/categories/{apiCategoryId}

Sample: /api-definitions/v1/categories/13

Content-Type: application/json

Request Body:

{
    "apiCategoryDescription": "web media delivery apis",
    "createdBy": "rdslj@akamai.com",
    "lockVersion": 139793907,
    "apiCategoryId": 13,
    "link": "/api-definitions/v1/categories/13",
    "updateDate": "2013-10-07T17:41:52+0000",
    "apiCategoryName": "Media Delivery",
    "updatedBy": "rajdj@akamai.com",
    "createDate": "2013-10-07T17:41:52+0000"
}
Parameter Type Sample Description
URL parameters
apiCategoryId Integer 13 Unique integer identifier for each category.

Status 200 application/json

Response Body:

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

  1. If you don’t have a full representation of the object you want to modify, run the List Categories operation.

  2. Choose the appropriate object from the response array and store its apiCategoryId.

  3. Run the Get a Category operation for a full representation of the object.

  4. Modify the Category object.

  5. PUT the object back to the same URL as the GET: /api-definitions/v1/categories/{apiCategoryId}.

A 200 response confirms success, and the response object reflects your modifications.

Remove a category

Removes a category that is not assigned to any API endpoints. If the category is assigned to an API, the operation responds with a 403 error.

DELETE /api-definitions/v1/categories/{apiCategoryId}

Sample: /api-definitions/v1/categories/13

Parameter Type Sample Description
URL parameters
apiCategoryId Integer 13 Unique integer identifier for each category.

Status 204

  1. To get the apiCategoryId of the category to delete, run the List Categories operation.

  2. Choose the appropriate object from the response array and store its apiCategoryId.

  3. Make a DELETE request to /api-definitions/v1/categories/{apiCategoryId}.

A 204 response confirms the Category object has been deleted.

List contracts and groups

Each API endpoint is provisioned within the context of your contract with Akamai and a Control Center portal group. This operation lists AcgPair objects. These encapsulate pairings of contract and group identifiers available within the scope of the user who provisioned the API token, as described in Getting Started.

GET /api-definitions/v1/contracts/groups

Status 200 application/json

Response Body:

[
    {
        "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,
        "contractId": "3-1Cgoa"
    }
]

List hostnames

List any hostnames for which users can access an endpoint service under a given contract and group pairing. Use Property Manager (or PAPI) to create new hostnames to make available to users.

GET /api-definitions/v1/contracts/{contractId}/groups/{groupId}/hosts

Sample: /api-definitions/v1/contracts/3-1Cgoa/groups/67890/hosts

Parameter Type Sample Description
URL parameters
contractId String 3–1Cgoa Unique identifier for each contract.
groupId Integer 67890 Unique identifier for each group.

Status 200 application/json

Response Body:

[
    "www.akamai.com",
    "www3.akamai.com"
]

  1. Run the List Contracts and Groups operation.

  2. From the response array, choose the appropriate pairing of contract and group, and store its contractId and groupId values.

  3. Make a GET request to /api-definitions/v1/contracts/{contractId}/groups/{groupId}/hosts.

The response features a simple array of available hostname strings.

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.

Download this API’s JSON 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 Control Center 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.
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.
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.
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[] ○ 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[]: Encapsulates information about the HTTP methods to which each resource may respond.
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.

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 authorization error, where the type values is a non-navigable URI, and the instance may be useful if you need to communicate about the problem with your Akamai support representative:

{
    "type": "https://problems.luna.akamaiapis.net/api-definitions/error-types/UNAUTHORIZED",
    "title": "Unauthorized Access/Action",
    "status": 403,
    "detail": "You don't have access to the end point.",
    "instance": "https://problems.luna.akamaiapis.net/api-definitions/error-instances/d54686b5-21cb-4ab7-a8d6-a92282cf1749"
}

HTTP status codes

The following lists the full range of response codes the API may generate:

Code Description
200 The operation was successful.
201 Resource successfully created.
204 Successfully processed request.
400 Bad Request.
401 Authentication failure.
403 Access is forbidden.
404 Resource not found.
405 Method not supported.
409 Conflict with current state of resource.
412 An Etag or If-Match header does not match, indicating the content has been modified. See Concurrency Control for more information.
500 Internal server error.

Last modified: 3/22/2017