API Endpoint Definition API 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 Luna portal group. The AcgPair object encapsulates this pairing of information.

NOTE: In the table below and for all other APIs listed on the Akamai Developer site, 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

Operation Method Endpoint
Endpoints   (download RAML)
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   (download RAML)
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   (download RAML)
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 Luna 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.


Last modified: 6/13/2017