
- Overview
- Resources
- API summary
- List endpoints
- Create a new endpoint
- Create a new API endpoint from a file upload
- Get an endpoint
- Modify an endpoint
- Remove an endpoint
- Upload a file to replace an endpoint’s resources
- List resources
- Create a new resource
- Get a resource
- Modify a resource
- Remove a resource
- List categories
- Create a new category
- Get a category
- Modify a category
- Remove a category
- List contracts and groups
- List hostnames
- Data
- Errors
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:
- Download this API’s RAML and JSON schema descriptors.
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.
Get started
Before using this API for the first time:
Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this:
https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net
.To enable this API, choose the API service named API Definition, and set the access level to READ-WRITE.
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/ |
Create a New Endpoint | POST | /api-definitions/ |
Create a New API Endpoint from a File Upload | POST | /api-definitions/ |
Get an Endpoint | GET | /api-definitions/ |
Modify an Endpoint | PUT | /api-definitions/ |
Remove an Endpoint | DELETE | /api-definitions/ |
Upload a File to Replace an Endpoint’s Resources | POST | /api-definitions/ |
List Resources | GET | /api-definitions/ |
Create a New Resource | POST | /api-definitions/ |
Get a Resource | GET | /api-definitions/ |
Modify a Resource | PUT | /api-definitions/ |
Remove a Resource | DELETE | /api-definitions/ |
Categories | ||
List Categories | GET | /api-definitions/ |
Create a New Category | POST | /api-definitions/ |
Get a Category | GET | /api-definitions/ |
Modify a Category | PUT | /api-definitions/ |
Remove a Category | DELETE | /api-definitions/ |
Contracts | ||
List Contracts and Groups | GET | /api-definitions/ |
List Hostnames | GET | /api-definitions/ |
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/
Sample: /api-definitions/
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
}
Optionally set the
contractId
andgroupId
query parameters to filter results provisioned under a specific pairing of contract and group.Optionally filter results to a specific
category
, or setcontains
to search on text.If you want to affect how output sorts, set the
sortBy
query parameter to eithername
orupdateDate
, or setsortOrder
toasc
ordesc
.If you want to modify pagination, set the
pageSize
query parameter for the number of records per page, and the overallpage
number.Make a GET request to
/api-definitions/
.v1/ endpoints{?page, pageSize, category, contains, sortBy, sortOrder, contractId, groupId} Optionally follow the hypermedia
links
to navigate to thenext
orprevious
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/
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"
}
Run the List Contracts and Groups operation.
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
andgroupId
values.Optionally run the List Categories operation and store
apiCategoryId
from the array of Category objects.Build an Endpoint object, specifying the
contractId
andgroupId
members, and a uniqueapiEndPointName
.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/
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"
}
Prepare an API descriptor file and set the
importFileFormat
toraml
orswagger
.Assign the filename as the
importFile
.Optionally embed the descriptor within a ZIP archive, in which case reset the descriptor filename as
root
and the name of the archive asimportFile
.Optionally make the descriptor or archive file available on the web at an
importUrl
.Run the List Contracts and Groups operation.
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
andgroupId
values.Prepare a
multipart/form-data
request specifying the fields listed in Parameters. Specify either animportFile
orimportUrl
, and make sure to specify theroot
if you are uploading a ZIP archive.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/
Sample: /api-definitions/
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"
}
If you don’t already have an
apiEndPointId
value, run the List Endpoints operation.Pick the appropriate endpoint from the
apiEndPoints
array and store itsapiEndPointId
.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/
Sample: /api-definitions/
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"
}
If you don’t have a full representation of the object you want to modify, run the List Endpoints operation.
Pick the appropriate endpoint from the
apiEndPoints
array and store itsapiEndPointId
.Run the Get an Endpoint operation for the complete representation of the object.
Modify the Endpoint object.
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/
Sample: /api-definitions/
Parameter | Type | Sample | Description |
---|---|---|---|
URL parameters | |||
apiEndPointId |
Integer | 12892 |
Unique integer identifier for each API endpoint service. |
Status 204
If you don’t already have an
apiEndPointId
value, run the List Endpoints operation.Pick the appropriate endpoint from the
apiEndPoints
array and store itsapiEndPointId
.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/
Sample: /api-definitions/
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"
}
If you don’t already have an
apiEndPointId
value, run the List Endpoints operation.Pick the appropriate endpoint from the
apiEndPoints
array and store itsapiEndPointId
.Prepare an API descriptor file and set the
importFileFormat
toraml
orswagger
.Assign the filename as the
importFile
.Optionally embed the descriptor within a ZIP archive, in which case reset the descriptor filename as
root
and the name of the archive asimportFile
.Optionally make the descriptor or archive file available on the web at an
importUrl
.Run the List Contracts and Groups operation.
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
andgroupId
values.Prepare a
multipart/form-data
request specifying the fields listed in Parameters. Specify either animportFile
orimportUrl
, and make sure to specify theroot
if you are uploading a ZIP archive.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/
Sample: /api-definitions/
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
}
]
If you don’t already have an
apiEndPointId
value, run the List Endpoints operation.Pick the appropriate endpoint from the
apiEndPoints
array and store itsapiEndPointId
.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/
Sample: /api-definitions/
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
}
]
Run the List Endpoints operation.
Pick the appropriate endpoint from the
apiEndPoints
array and store itsapiEndPointId
.Build a Resource object. The only initial requirements are for a
resourcePath
and anapiResourceName
, which both need to be unique within the API endpoint service.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/
Sample: /api-definitions/
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
}
]
If you don’t already have an
apiEndPointId
value, run the List Endpoints operation.Pick the appropriate endpoint from the
apiEndPoints
array and store itsapiEndPointId
.If you don’t already have an
apiResourceId
value, run the List Resources operation.From the response array, choose the appropriate object and store its
apiResourceId
.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/
Sample: /api-definitions/
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
}
]
If you don’t have a full representation of the object you want to modify, run the List Endpoints operation.
Pick the appropriate endpoint from the
apiEndPoints
array and store itsapiEndPointId
.Run the List Resources operation.
From the response array, choose the appropriate object and store its
apiResourceId
.Run the Get a Resource operation for the full representation of the object.
Modify the Resource object.
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/
Sample: /api-definitions/
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
If you don’t already have an
apiEndPointId
value, run the List Endpoints operation.Pick the appropriate endpoint from the
apiEndPoints
array and store itsapiEndPointId
.If you don’t already have an
apiResourceId
value, run the List Resources operation.From the response array, choose the appropriate object and store its
apiResourceId
.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/
Sample: /api-definitions/
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__"
}
]
Optionally set the
withUsageInfo
query parameter totrue
if you want listed categories to show the number of APIs they apply to.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/
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"
}
Get a category
Get a specific category used to tag API endpoints.
GET /api-definitions/
Sample: /api-definitions/
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"
}
Run the List Categories operation.
Choose the appropriate object from the response array and store its
apiCategoryId
.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/
Sample: /api-definitions/
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"
}
If you don’t have a full representation of the object you want to modify, run the List Categories operation.
Choose the appropriate object from the response array and store its
apiCategoryId
.Run the Get a Category operation for a full representation of the object.
Modify the Category object.
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/
Sample: /api-definitions/
Parameter | Type | Sample | Description |
---|---|---|---|
URL parameters | |||
apiCategoryId |
Integer | 13 |
Unique integer identifier for each category. |
Status 204
To get the
apiCategoryId
of the category to delete, run the List Categories operation.Choose the appropriate object from the response array and store its
apiCategoryId
.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 Get started.
GET /api-definitions/
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/
Sample: /api-definitions/
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"
]
Run the List Contracts and Groups operation.
From the response array, choose the appropriate pairing of contract and group, and store its
contractId
andgroupId
values.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. |
○ | 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. |
○ | 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. |
✓ | 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. |
○ | 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. |