API Endpoint Definition API Resources

The API Endpoint Definition API allows you to programmatically define an API endpoint and its set of component resources. If you’re a Kona Site Defender customer, you can define request body and resource constraints and enforce them separately as whitelists in a Kona Site Defender firewall policy. If you have access to Akamai API Gateway settings, you can also configure JWT validation, CORS, caching, GZIP compression, and API privacy.

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.

  • A version is the API version that you set up to make your endpoint, resource, and delivery configurations effective. You can activate an API version in the Akamai staging or production environment.

  • The delivery settings let you configure API privacy, JWT validation, CORS, caching, and GZIP compression. Enabling these features can help you manage your your APIs more efficiently, improve interoperability, and enhance the overall performance of your API traffic.

  • 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

Download the RAML descriptors for this API.

Operation Method Endpoint
Endpoints  
List Endpoints GET /api-definitions/v2/endpoints{?page,pageSize,category,contains,sortBy,sortOrder,versionPreference,contractId,groupId}
Create an Endpoint POST /api-definitions/v2/endpoints
Clone an Endpoint POST /api-definitions/v2/endpoints/cloneEndpoint
Create an Endpoint from an API Definition File POST /api-definitions/v2/endpoints/files
List User Entitlements GET /api-definitions/v2/endpoints/user-entitlements
Remove an Endpoint DELETE /api-definitions/v2/endpoints/{apiEndPointId}
List Versions GET /api-definitions/v2/endpoints/{apiEndPointId}/versions
Get a Version Summary GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}
Modify a Version PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}
Remove a Version DELETE /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}
Update an Endpoint from an API Definition File POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/file
Get a Version GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources-detail
Clone a Version POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/cloneVersion
Activate a Version POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/activate
Deactivate a Version POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/deactivate
List Resources GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources
Create a Resource POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources
Get a Resource GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources/{apiResourceId}
Modify a Resource PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources/{apiResourceId}
Remove a Resource DELETE /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources/{apiResourceId}
Endpoint Settings  
Get Cache Settings GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cache
Update Cache Settings PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cache
Get GZIP Settings GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/gzip
Update GZIP Settings PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/gzip
Get CORS Settings GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cors
Update CORS Settings PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cors
Get JWT Settings GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/jwt
Update JWT Settings PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/jwt
Get API Privacy Settings GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/api-privacy
Update API Privacy Settings PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/api-privacy
Categories  
List Categories GET /api-definitions/v2/categories{?withUsageInfo}
Create a Category POST /api-definitions/v2/categories
Get a Category GET /api-definitions/v2/categories/{apiCategoryId}
Modify a Category PUT /api-definitions/v2/categories/{apiCategoryId}
Remove a Category DELETE /api-definitions/v2/categories/{apiCategoryId}
Contracts  
List Contracts and Groups GET /api-definitions/v2/contracts/groups
List Hostnames GET /api-definitions/v2/contracts/{contractId}/groups/{groupId}/hosts

List Endpoints

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

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

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

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 The search query substring criteria matching the endpoint’s name, description, basePath, apiCategoryName, and resourcePath.
contractId String 1-xc789 Filters endpoints to a specific contract. You need to specify this along with a groupId.
groupId Integer 67890 Filters endpoints 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 endpoints on each page of results, 25 by default.
sortBy Enumeration updateDate The field to sort endpoints by, either the API name (corresponding to the apiEndPointName member) or updateDate.
sortOrder Enumeration asc The sort order, either desc for descending or the default asc for ascending.
versionPreference Enumeration ACTIVATED_FIRST The preference for picking the endpoint version to return. By default the API returns the LAST_UPDATED version. If you set the preference to ACTIVATED_FIRST, the API first attempts to return the version currently active on the production network. If such version doesn’t exist, the API attempts to return the version currently active on the staging network. If both of these checks fail, the API returns the last updated version.

Status 200 application/json

Response Body:

{
    "totalSize": 15,
    "page": 8,
    "pageSize": 2,
    "apiEndPoints": [
        {
            "createdBy": "joe1",
            "createDate": "2016-09-29T03:30:27+0000",
            "updateDate": "2016-09-29T03:30:27+0000",
            "updatedBy": "joe1",
            "apiEndPointId": 81,
            "apiEndPointName": "Membership Benefits",
            "description": "Provides information about membership benefits and available services.",
            "basePath": "/v2",
            "apiEndPointScheme": "https",
            "consumeType": "json",
            "contractId": "3-13H55B5",
            "groupId": 44681,
            "versionNumber": 1,
            "clonedFromVersion": null,
            "apiEndPointLocked": false,
            "stagingVersion": {
                "versionNumber": null,
                "status": null
            },
            "productionVersion": {
                "versionNumber": null,
                "status": null
            },
            "protectedByApiKey": false,
            "apiEndPointHosts": [
                "api-service.example.com"
            ],
            "apiCategoryIds": [],
            "apiResourceBaseInfo": [
                {
                    "createdBy": "joe1",
                    "createDate": "2016-09-29T03:30:32+0000",
                    "updateDate": "2016-09-29T03:30:32+0000",
                    "updatedBy": "joe1",
                    "apiResourceId": 43,
                    "apiResourceName": "/locations/{location-id}",
                    "resourcePath": "/locations/{location-id}",
                    "description": null,
                    "link": null,
                    "apiResourceClonedFromId": null,
                    "apiResourceLogicId": 43,
                    "private": false,
                    "lockVersion": 0
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "/api-definitions/v2/endpoints?pageSize=2&page=8"
        },
        {
            "rel": "next",
            "href": "/api-definitions/v2/endpoints?pageSize=2&page=9"
        },
        {
            "rel": "previous",
            "href": "/api-definitions/v2/endpoints?pageSize=2&page=7"
        }
    ]
}
  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. If you want to change the default version preference and return the last activated version for each endpoint, set the versionPreference value to ACTIVATED_FIRST.

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

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

Create an Endpoint

This operation creates the first version of an API endpoint configuration with or without resources. The endpoint’s name has to be unique within the account.

POST /api-definitions/v2/endpoints

Content-Type: application/json

Request Body:

{
    "apiEndPointName": "Membership Benefits",
    "description": "Provides information about membership benefits and available services.",
    "basePath": "/api/v2",
    "apiEndPointScheme": "http/https",
    "consumeType": "any",
    "groupId": 44681,
    "apiEndPointHosts": [
        "api-service.example.com"
    ],
    "apiCategoryIds": [
        161
    ],
    "contractId": "3-13H55B5",
    "securityScheme": {
        "securitySchemeType": "apikey",
        "securitySchemeDetail": {
            "apiKeyLocation": "header",
            "apiKeyName": "header-101"
        }
    },
    "akamaiSecurityRestrictions": {
        "MAX_JSONXML_ELEMENT": 1032,
        "MAX_ELEMENT_NAME_LENGTH": 256,
        "MAX_DOC_DEPTH": 64,
        "POSITIVE_SECURITY_ENABLED": 1,
        "MAX_STRING_LENGTH": 8192,
        "MAX_BODY_SIZE": 61056,
        "MAX_INTEGER_VALUE": 9999
    },
    "apiResources": [
        {
            "apiResourceName": "cloud security",
            "resourcePath": "/resources/{resourceId}",
            "description": "resource description",
            "apiResourceMethods": [
                {
                    "apiResourceMethod": "GET",
                    "apiParameters": [
                        {
                            "apiParameterRequired": true,
                            "apiParameterName": "endpoint-id",
                            "apiParameterLocation": "path",
                            "apiParameterType": "integer",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": {
                                "rangeRestriction": {
                                    "rangeMin": 6,
                                    "rangeMax": 15
                                }
                            }
                        },
                        {
                            "apiParameterRequired": true,
                            "apiParameterName": "resourceId",
                            "apiParameterLocation": "path",
                            "apiParameterType": "string",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null
                        }
                    ]
                },
                {
                    "apiResourceMethod": "POST",
                    "apiParameters": [
                        {
                            "apiParameterRequired": true,
                            "apiParameterName": "endpoint-id",
                            "apiParameterLocation": "path",
                            "apiParameterType": "integer",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null
                        },
                        {
                            "apiParameterRequired": true,
                            "apiParameterName": "resourceId",
                            "apiParameterLocation": "path",
                            "apiParameterType": "string",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": {
                                "lengthRestriction": {
                                    "lengthMax": 15,
                                    "lengthMin": 6
                                }
                            }
                        },
                        {
                            "apiParameterRequired": true,
                            "apiParameterName": "post-body",
                            "apiParameterLocation": "body",
                            "apiParameterType": "json/xml",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null,
                            "apiChildParameters": [
                                {
                                    "apiParameterRequired": true,
                                    "apiParameterName": "id",
                                    "apiParameterLocation": "body",
                                    "apiParameterType": "integer",
                                    "apiParameterNotes": null,
                                    "array": false,
                                    "apiParameterRestriction": {
                                        "rangeRestriction": {
                                            "rangeMin": 6,
                                            "rangeMax": 15
                                        },
                                        "xmlConversionRule": {
                                            "name": null,
                                            "prefix": "idx",
                                            "namespace": "https://www.abc.com/schema/xap.xsd",
                                            "attribute": false,
                                            "wrapped": false
                                        }
                                    }
                                },
                                {
                                    "apiParameterRequired": true,
                                    "apiParameterName": "name",
                                    "apiParameterLocation": "body",
                                    "apiParameterType": "String",
                                    "apiParameterNotes": null,
                                    "array": false,
                                    "apiParameterRestriction": null
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Status 201 application/json

Headers:

Location: /api-definitions/v2/endpoints/123/versions/1

Response Body:

{
    "createdBy": "joe1",
    "createDate": "2017-11-17T19:27:07+0000",
    "updateDate": "2017-11-17T19:27:07+0000",
    "updatedBy": "joe1",
    "apiEndPointId": 314252,
    "apiEndPointName": "Membership Benefits",
    "description": "Provides information about membership benefits and available services.",
    "basePath": "/api/v2",
    "apiEndPointScheme": "http/https",
    "consumeType": "any",
    "groupId": 44681,
    "versionNumber": 1,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "stagingVersion": {
        "versionNumber": null,
        "status": null
    },
    "productionVersion": {
        "versionNumber": null,
        "status": null
    },
    "protectedByApiKey": false,
    "apiEndPointHosts": [
        "api-service.example.com"
    ],
    "apiCategoryIds": [
        161
    ],
    "contractId": "3-13H55B5",
    "securityScheme": {
        "securitySchemeType": "apikey",
        "securitySchemeDetail": {
            "apiKeyLocation": "header",
            "apiKeyName": "header-101"
        }
    },
    "akamaiSecurityRestrictions": {
        "MAX_JSONXML_ELEMENT": 1032,
        "MAX_ELEMENT_NAME_LENGTH": 256,
        "MAX_DOC_DEPTH": 64,
        "POSITIVE_SECURITY_ENABLED": 1,
        "MAX_STRING_LENGTH": 8192,
        "MAX_BODY_SIZE": 61056,
        "MAX_INTEGER_VALUE": 9999
    },
    "stagingStatus": null,
    "productionStatus": null,
    "apiResources": [
        {
            "apiResourceId": 765432,
            "apiResourceName": "cloud security",
            "resourcePath": "/resources/{resourceId}",
            "description": "resource description",
            "apiResourceMethods": [
                {
                    "apiResourceMethodId": 54362,
                    "apiResourceMethod": "GET",
                    "apiParameters": [
                        {
                            "apiParameterId": 23245,
                            "apiParameterRequired": true,
                            "apiParameterName": "endpoint-id",
                            "apiParameterLocation": "path",
                            "apiParameterType": "integer",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": {
                                "rangeRestriction": {
                                    "rangeMin": 6,
                                    "rangeMax": 15
                                }
                            }
                        },
                        {
                            "apiParameterId": 43212,
                            "apiParameterRequired": true,
                            "apiParameterName": "resourceId",
                            "apiParameterLocation": "path",
                            "apiParameterType": "string",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null
                        }
                    ]
                },
                {
                    "apiResourceMethodId": 43245,
                    "apiResourceMethod": "POST",
                    "apiParameters": [
                        {
                            "apiParameterId": 54353,
                            "apiParameterRequired": true,
                            "apiParameterName": "endpoint-id",
                            "apiParameterLocation": "path",
                            "apiParameterType": "integer",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null
                        },
                        {
                            "apiParameterId": 32314,
                            "apiParameterRequired": true,
                            "apiParameterName": "resourceId",
                            "apiParameterLocation": "path",
                            "apiParameterType": "string",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": {
                                "lengthRestriction": {
                                    "lengthMax": 15,
                                    "lengthMin": 6
                                }
                            }
                        },
                        {
                            "apiParameterId": 32454,
                            "apiParameterRequired": true,
                            "apiParameterName": "post-body",
                            "apiParameterLocation": "body",
                            "apiParameterType": "json/xml",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null,
                            "apiChildParameters": [
                                {
                                    "apiParameterId": 32456,
                                    "apiParameterRequired": true,
                                    "apiParameterName": "id",
                                    "apiParameterLocation": "body",
                                    "apiParameterType": "integer",
                                    "apiParameterNotes": null,
                                    "array": false,
                                    "apiParameterRestriction": {
                                        "rangeRestriction": {
                                            "rangeMin": 6,
                                            "rangeMax": 15
                                        },
                                        "xmlConversionRule": {
                                            "name": null,
                                            "prefix": "idx",
                                            "namespace": "https://www.abc.com/schema/xap.xsd",
                                            "attribute": false,
                                            "wrapped": false
                                        }
                                    }
                                },
                                {
                                    "apiParameterId": 32124,
                                    "apiParameterRequired": true,
                                    "apiParameterName": "name",
                                    "apiParameterLocation": "body",
                                    "apiParameterType": "String",
                                    "apiParameterNotes": null,
                                    "array": false,
                                    "apiParameterRestriction": null
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "lockVersion": 1
}
  1. If you don’t already have the contractId and groupId members, run the List Contracts and Groups operation.

  2. Pick the appropriate pairing of contract and group under which you want to provision the new endpoint. Store the contractId and groupId values.

  3. If you want to tag the new endpoint with optional categories, run the List Categories operation and store the appropriate apiCategoryId values from the array of Category objects.

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

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

The response reflects back the complete Endpoint object, from which you can store the apiEndPointId value. You can access the newly created endpoint at the URL specified in the Location response header.

Clone an Endpoint

This operation creates an endpoint as a clone from the specified source endpoint ID and version.

POST /api-definitions/v2/endpoints/cloneEndpoint

Content-Type: application/json

Request Body:

{
    "versionNumber": 1,
    "apiEndPointId": 313304,
    "apiEndPointName": "Membership Benefits",
    "basePath": "/api-basepath",
    "apiEndPointHosts": [
        "api-service.example.com"
    ],
    "contractId": "3-13H55B5",
    "groupId": 44680
}

Status 200 application/json

Response Body:

{
    "createdBy": "ccare2",
    "createDate": "2017-09-06T16:15:44+0000",
    "updateDate": "2017-09-06T16:15:44+0000",
    "updatedBy": "ccare2",
    "apiEndPointId": 313305,
    "apiEndPointName": "Membership Benefits",
    "description": null,
    "basePath": "/api-basepath",
    "apiEndPointScheme": null,
    "consumeType": "any",
    "groupId": 44680,
    "versionNumber": 2,
    "clonedFromVersion": 1,
    "apiEndPointLocked": false,
    "stagingVersion": {
        "versionNumber": null,
        "status": null
    },
    "productionVersion": {
        "versionNumber": null,
        "status": null
    },
    "apiEndPointHosts": [
        "api-service.example.com"
    ],
    "apiCategoryIds": [
        1123
    ],
    "contractId": "3-13H55B5",
    "securityScheme": {
        "securitySchemeType": "apikey",
        "securitySchemeDetail": {
            "apiKeyLocation": "header",
            "apiKeyName": "header-api"
        }
    },
    "akamaiSecurityRestrictions": {
        "MAX_JSONXML_ELEMENT": 10,
        "MAX_ELEMENT_NAME_LENGTH": 256,
        "POSITIVE_SECURITY_ENABLED": 1,
        "MAX_DOC_DEPTH": 64,
        "MAX_BODY_SIZE": 23433454,
        "MAX_STRING_LENGTH": 999999999999,
        "MAX_INTEGER_VALUE": 999999999
    },
    "stagingStatus": null,
    "productionStatus": null,
    "apiResources": [
        {
            "createdBy": "ccare2",
            "createDate": "2017-09-06T16:15:45+0000",
            "updateDate": "2017-09-06T16:15:45+0000",
            "updatedBy": "ccare2",
            "apiResourceId": 12943,
            "apiResourceName": "Billing",
            "resourcePath": "/billing",
            "description": "Billing data",
            "link": null,
            "apiResourceClonedFromId": null,
            "apiResourceLogicId": 14180,
            "apiResourceMethods": [
                {
                    "apiResourceMethodId": 30135,
                    "apiResourceMethod": "GET",
                    "apiParameters": [
                        {
                            "apiParameterId": 35545,
                            "apiParameterRequired": true,
                            "apiParameterName": "param1",
                            "apiParameterLocation": "header",
                            "apiParameterType": "integer",
                            "array": false,
                            "apiParamLogicId": 32645,
                            "apiResourceMethParamId": 19682,
                            "apiChildParameters": [],
                            "apiParameterRestriction": {
                                "lengthRestriction": null,
                                "rangeRestriction": {
                                    "rangeMin": null,
                                    "rangeMax": null
                                },
                                "numberRangeRestriction": null,
                                "arrayRestriction": null,
                                "xmlConversionRule": null
                            },
                            "apiParameterNotes": null
                        },
                        {
                            "apiParameterId": 35546,
                            "apiParameterRequired": false,
                            "apiParameterName": "param-2",
                            "apiParameterLocation": "cookie",
                            "apiParameterType": "number",
                            "array": false,
                            "apiParamLogicId": 32646,
                            "apiResourceMethParamId": 19683,
                            "apiChildParameters": [],
                            "apiParameterRestriction": {
                                "lengthRestriction": null,
                                "rangeRestriction": null,
                                "numberRangeRestriction": {
                                    "numberRangeMin": null,
                                    "numberRangeMax": 999999.0
                                },
                                "arrayRestriction": null,
                                "xmlConversionRule": null
                            },
                            "apiParameterNotes": null
                        }
                    ],
                    "apiResourceMethodLogicId": 25615
                },
                {
                    "apiResourceMethodId": 30136,
                    "apiResourceMethod": "POST",
                    "apiParameters": [
                        {
                            "apiParameterId": 35547,
                            "apiParameterRequired": false,
                            "apiParameterName": "body-param",
                            "apiParameterLocation": "body",
                            "apiParameterType": "json/xml",
                            "array": false,
                            "apiParamLogicId": 32647,
                            "apiResourceMethParamId": 19684,
                            "apiChildParameters": [
                                {
                                    "apiParameterId": 35548,
                                    "apiParameterRequired": true,
                                    "apiParameterName": "root",
                                    "apiParameterLocation": null,
                                    "apiParameterType": "json/xml",
                                    "array": false,
                                    "apiParamLogicId": 32648,
                                    "apiResourceMethParamId": null,
                                    "apiChildParameters": [
                                        {
                                            "apiParameterId": 35549,
                                            "apiParameterRequired": false,
                                            "apiParameterName": "param1",
                                            "apiParameterLocation": null,
                                            "apiParameterType": "integer",
                                            "array": false,
                                            "apiParamLogicId": 32649,
                                            "apiResourceMethParamId": null,
                                            "apiChildParameters": [],
                                            "apiParameterRestriction": {
                                                "lengthRestriction": null,
                                                "rangeRestriction": {
                                                    "rangeMin": 1,
                                                    "rangeMax": 999
                                                },
                                                "numberRangeRestriction": null,
                                                "arrayRestriction": null,
                                                "xmlConversionRule": null
                                            },
                                            "apiParameterNotes": null
                                        },
                                        {
                                            "apiParameterId": 35550,
                                            "apiParameterRequired": false,
                                            "apiParameterName": "param-2",
                                            "apiParameterLocation": null,
                                            "apiParameterType": "number",
                                            "array": false,
                                            "apiParamLogicId": 32650,
                                            "apiResourceMethParamId": null,
                                            "apiChildParameters": [],
                                            "apiParameterRestriction": {
                                                "lengthRestriction": null,
                                                "rangeRestriction": null,
                                                "numberRangeRestriction": {
                                                    "numberRangeMin": -999.0,
                                                    "numberRangeMax": 999.0
                                                },
                                                "arrayRestriction": null,
                                                "xmlConversionRule": null
                                            },
                                            "apiParameterNotes": null
                                        }
                                    ],
                                    "apiParameterRestriction": null,
                                    "apiParameterNotes": null
                                }
                            ],
                            "apiParameterRestriction": null,
                            "apiParameterNotes": null
                        }
                    ],
                    "apiResourceMethodLogicId": 25616
                }
            ],
            "lockVersion": 2
        }
    ],
    "lockVersion": 2
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. If you don’t already have the contractId and groupId members, run the List Contracts and Groups operation.

  6. Pick the appropriate pairing of contract and group under which you want to provision the new endpoint. Store the contractId and groupId values.

  7. Build an Endpoint object, specifying the contractId and groupId members, the apiEndpointId of the source endpoint, the versionNumber of the version you want to clone, the basePath, apiEndPointHosts, and a unique apiEndPointName for the new endpoint.

  8. POST the object to /api-definitions/v2/endpoints.

The response reflects back the complete Endpoint object, from which you can store the apiEndPointId value. You can access the newly created endpoint at the URL specified in the Location response header.

Create an Endpoint from an API Definition File

This operation imports an API definition file and creates a new endpoint based on the file contents. You either upload or specify a URL to a Swagger 2.0 or RAML 0.8 file to import details about your API. For this operation, you make a multipart/form-data request with the form parameters listed on the Parameters tab. For details on multipart/form-data requests, see RFC 2388.

POST /api-definitions/v2/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 definition file, 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 definition file.
root String api_descriptor.raml If the import file is a ZIP archive, this identifies the API definition’s filename within the archive.
contractId String 3-1Cgoa The unique identifier for the contract under which to provision the endpoint.
groupId String 67890 The unique identifier for the group under which to provision the endpoint.

Status 201 application/json

Headers:

Location: /api-definitions/v2/endpoints/123/versions/1

Response Body:

{
    "createdBy": "joe1",
    "createDate": "2017-09-06T16:15:44+0000",
    "updateDate": "2017-09-06T16:15:44+0000",
    "updatedBy": "joe1",
    "apiEndPointId": 289157,
    "apiEndPointName": "Membership Benefits",
    "description": null,
    "basePath": "/api/v2",
    "apiEndPointScheme": null,
    "consumeType": "any",
    "groupId": 44681,
    "versionNumber": 1,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "protectedByApiKey": false,
    "stagingVersion": {
        "versionNumber": null,
        "status": null
    },
    "productionVersion": {
        "versionNumber": null,
        "status": null
    },
    "apiEndPointHosts": [
        "api-service.example.com"
    ],
    "apiCategoryIds": [
        1123
    ],
    "contractId": "3-13H55B5",
    "securityScheme": {
        "securitySchemeType": "apikey",
        "securitySchemeDetail": {
            "apiKeyLocation": "header",
            "apiKeyName": "header-api"
        }
    },
    "akamaiSecurityRestrictions": {
        "MAX_JSONXML_ELEMENT": 10,
        "MAX_ELEMENT_NAME_LENGTH": 256,
        "POSITIVE_SECURITY_ENABLED": 1,
        "MAX_DOC_DEPTH": 64,
        "MAX_BODY_SIZE": 23433454,
        "MAX_STRING_LENGTH": 999999999999,
        "MAX_INTEGER_VALUE": 999999999
    },
    "stagingStatus": null,
    "productionStatus": null,
    "apiResources": [
        {
            "createdBy": "joe1",
            "createDate": "2017-09-06T16:15:45+0000",
            "updateDate": "2017-09-06T16:15:45+0000",
            "updatedBy": "joe1",
            "apiResourceId": 12943,
            "apiResourceName": "Billing",
            "resourcePath": "/billing",
            "description": "Billing data",
            "link": null,
            "apiResourceClonedFromId": null,
            "apiResourceLogicId": 14180,
            "apiResourceMethods": [
                {
                    "apiResourceMethodId": 30135,
                    "apiResourceMethod": "GET",
                    "apiParameters": [
                        {
                            "apiParameterId": 35545,
                            "apiParameterRequired": true,
                            "apiParameterName": "param1",
                            "apiParameterLocation": "header",
                            "apiParameterType": "integer",
                            "array": false,
                            "apiParamLogicId": 32645,
                            "apiResourceMethParamId": 19682,
                            "apiChildParameters": [],
                            "apiParameterRestriction": {
                                "lengthRestriction": null,
                                "rangeRestriction": {
                                    "rangeMin": null,
                                    "rangeMax": null
                                },
                                "numberRangeRestriction": null,
                                "arrayRestriction": null,
                                "xmlConversionRule": null
                            },
                            "apiParameterNotes": null
                        },
                        {
                            "apiParameterId": 35546,
                            "apiParameterRequired": false,
                            "apiParameterName": "param-2",
                            "apiParameterLocation": "cookie",
                            "apiParameterType": "number",
                            "array": false,
                            "apiParamLogicId": 32646,
                            "apiResourceMethParamId": 19683,
                            "apiChildParameters": [],
                            "apiParameterRestriction": {
                                "lengthRestriction": null,
                                "rangeRestriction": null,
                                "numberRangeRestriction": {
                                    "numberRangeMin": null,
                                    "numberRangeMax": 999999.0
                                },
                                "arrayRestriction": null,
                                "xmlConversionRule": null
                            },
                            "apiParameterNotes": null
                        }
                    ],
                    "apiResourceMethodLogicId": 25615
                },
                {
                    "apiResourceMethodId": 30136,
                    "apiResourceMethod": "POST",
                    "apiParameters": [
                        {
                            "apiParameterId": 35547,
                            "apiParameterRequired": false,
                            "apiParameterName": "body-param",
                            "apiParameterLocation": "body",
                            "apiParameterType": "json/xml",
                            "array": false,
                            "apiParamLogicId": 32647,
                            "apiResourceMethParamId": 19684,
                            "apiChildParameters": [
                                {
                                    "apiParameterId": 35548,
                                    "apiParameterRequired": true,
                                    "apiParameterName": "root",
                                    "apiParameterLocation": null,
                                    "apiParameterType": "json/xml",
                                    "array": false,
                                    "apiParamLogicId": 32648,
                                    "apiResourceMethParamId": null,
                                    "apiChildParameters": [
                                        {
                                            "apiParameterId": 35549,
                                            "apiParameterRequired": false,
                                            "apiParameterName": "param1",
                                            "apiParameterLocation": null,
                                            "apiParameterType": "integer",
                                            "array": false,
                                            "apiParamLogicId": 32649,
                                            "apiResourceMethParamId": null,
                                            "apiChildParameters": [],
                                            "apiParameterRestriction": {
                                                "lengthRestriction": null,
                                                "rangeRestriction": {
                                                    "rangeMin": 1,
                                                    "rangeMax": 999
                                                },
                                                "numberRangeRestriction": null,
                                                "arrayRestriction": null,
                                                "xmlConversionRule": null
                                            },
                                            "apiParameterNotes": null
                                        },
                                        {
                                            "apiParameterId": 35550,
                                            "apiParameterRequired": false,
                                            "apiParameterName": "param-2",
                                            "apiParameterLocation": null,
                                            "apiParameterType": "number",
                                            "array": false,
                                            "apiParamLogicId": 32650,
                                            "apiResourceMethParamId": null,
                                            "apiChildParameters": [],
                                            "apiParameterRestriction": {
                                                "lengthRestriction": null,
                                                "rangeRestriction": null,
                                                "numberRangeRestriction": {
                                                    "numberRangeMin": -999.0,
                                                    "numberRangeMax": 999.0
                                                },
                                                "arrayRestriction": null,
                                                "xmlConversionRule": null
                                            },
                                            "apiParameterNotes": null
                                        }
                                    ],
                                    "apiParameterRestriction": null,
                                    "apiParameterNotes": null
                                }
                            ],
                            "apiParameterRestriction": null,
                            "apiParameterNotes": null
                        }
                    ],
                    "apiResourceMethodLogicId": 25616
                }
            ],
            "lockVersion": 1
        }
    ],
    "lockVersion": 1
}
  1. Prepare an API definition file and set the importFileFormat to raml or swagger.

  2. Assign the filename as the importFile.

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

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

  5. If you don’t already have the obligatory contractId and groupId members, run the List Contracts and Groups operation.

  6. Pick the appropriate pairing of contract and group under which you want to provision the new endpoint. 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/v2/endpoints/files.

The response Endpoint object reflects the newly created endpoint based on your definition file.

List User Entitlements

This operations lists user entitlements based on your assigned permissions. The values include API_READ for read-only access, API_WRITE for modifying the existing endpoint versions, API_VERSIONING for version management, API_FEATURES for access to Kona Site Defender security features, AAG_FEATURES for access to delivery features, and API_PURPOSE for access to resource purpose settings. Note that the API_FEATURES permission is only available for Kona Site Defender customers, and the API_PURPOSE permission is for Bot Manager customers.

GET /api-definitions/v2/endpoints/user-entitlements

Status 200 application/json

Response Body:

[
    "API_READ",
    "API_WRITE",
    "API_VERSIONING",
    "API_FEATURES"
]

Remove an Endpoint

This operation removes an endpoint configuration from Akamai API Gateway if none of the endpoint’s versions are active or pending activation on the staging or production network.

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

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

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.

Status 204

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

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

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

A 204 response confirms the Endpoint object has been deleted.

List Versions

This operation returns all versions of an endpoint.

GET /api-definitions/v2/endpoints/{apiEndPointId}/versions

Sample: /api-definitions/v2/endpoints/12892/versions

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.

Status 200 application/json

Response Body:

{
    "apiEndPointId": 288194,
    "apiEndPointName": "AAG Automation",
    "apiVersions": [
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:02:53+0000",
            "updateDate": "2017-09-06T13:02:53+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320167,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": null,
            "stagingStatus": null,
            "productionStatus": null,
            "stagingDate": null,
            "productionDate": null,
            "isVersionLocked": false,
            "availableActions": [
                "CLONE",
                "DELETE",
                "VIEW_AAG_SETTINGS",
                "EDIT_AAG_SETTINGS",
                "EDIT_ENDPOINT_DEFINITION",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 1,
            "lockVersion": 0
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:02:54+0000",
            "updateDate": "2017-09-06T13:08:13+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320168,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": "DEACTIVATED",
            "productionStatus": null,
            "stagingDate": "2017-09-06T13:13:04+0000",
            "productionDate": null,
            "isVersionLocked": true,
            "availableActions": [
                "CLONE",
                "VIEW_AAG_SETTINGS",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 2,
            "lockVersion": 3
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:08:12+0000",
            "updateDate": "2017-09-06T13:18:25+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320169,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": "DEACTIVATED",
            "productionStatus": null,
            "stagingDate": "2017-09-06T13:23:04+0000",
            "productionDate": null,
            "isVersionLocked": true,
            "availableActions": [
                "CLONE",
                "VIEW_AAG_SETTINGS",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 3,
            "lockVersion": 3
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:08:16+0000",
            "updateDate": "2017-09-06T13:24:09+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320170,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": "DEACTIVATED",
            "productionStatus": null,
            "stagingDate": "2017-09-06T13:30:06+0000",
            "productionDate": null,
            "isVersionLocked": true,
            "availableActions": [
                "CLONE",
                "VIEW_AAG_SETTINGS",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 4,
            "lockVersion": 3
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:18:26+0000",
            "updateDate": "2017-09-06T13:18:26+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320171,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": null,
            "productionStatus": null,
            "stagingDate": null,
            "productionDate": null,
            "isVersionLocked": false,
            "availableActions": [
                "CLONE",
                "DELETE",
                "VIEW_AAG_SETTINGS",
                "EDIT_AAG_SETTINGS",
                "EDIT_ENDPOINT_DEFINITION",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 5,
            "lockVersion": 0
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:18:29+0000",
            "updateDate": "2017-09-06T13:18:29+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320172,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": null,
            "productionStatus": null,
            "stagingDate": null,
            "productionDate": null,
            "isVersionLocked": false,
            "availableActions": [
                "CLONE",
                "DELETE",
                "VIEW_AAG_SETTINGS",
                "EDIT_AAG_SETTINGS",
                "EDIT_ENDPOINT_DEFINITION",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 6,
            "lockVersion": 0
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:18:31+0000",
            "updateDate": "2017-09-06T13:18:31+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320173,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": null,
            "productionStatus": null,
            "stagingDate": null,
            "productionDate": null,
            "isVersionLocked": false,
            "availableActions": [
                "CLONE",
                "DELETE",
                "VIEW_AAG_SETTINGS",
                "EDIT_AAG_SETTINGS",
                "EDIT_ENDPOINT_DEFINITION",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 7,
            "lockVersion": 0
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:18:33+0000",
            "updateDate": "2017-09-06T13:18:33+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320174,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": null,
            "productionStatus": null,
            "stagingDate": null,
            "productionDate": null,
            "isVersionLocked": false,
            "availableActions": [
                "CLONE",
                "DELETE",
                "VIEW_AAG_SETTINGS",
                "EDIT_AAG_SETTINGS",
                "EDIT_ENDPOINT_DEFINITION",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 8,
            "lockVersion": 0
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:18:34+0000",
            "updateDate": "2017-09-06T13:18:34+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320175,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": null,
            "productionStatus": null,
            "stagingDate": null,
            "productionDate": null,
            "isVersionLocked": false,
            "availableActions": [
                "CLONE",
                "DELETE",
                "VIEW_AAG_SETTINGS",
                "EDIT_AAG_SETTINGS",
                "EDIT_ENDPOINT_DEFINITION",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 9,
            "lockVersion": 0
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:18:38+0000",
            "updateDate": "2017-09-06T13:24:06+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320176,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": null,
            "productionStatus": "DEACTIVATED",
            "stagingDate": null,
            "productionDate": "2017-09-06T13:31:04+0000",
            "isVersionLocked": true,
            "availableActions": [
                "CLONE",
                "VIEW_AAG_SETTINGS",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 10,
            "lockVersion": 4
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:24:07+0000",
            "updateDate": "2017-09-06T13:24:09+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320177,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": "ACTIVE",
            "productionStatus": null,
            "stagingDate": "2017-09-06T13:30:06+0000",
            "productionDate": null,
            "isVersionLocked": true,
            "availableActions": [
                "CLONE",
                "VIEW_AAG_SETTINGS",
                "DEACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 11,
            "lockVersion": 2
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:24:12+0000",
            "updateDate": "2017-09-06T13:24:12+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320178,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": null,
            "productionStatus": null,
            "stagingDate": null,
            "productionDate": null,
            "isVersionLocked": false,
            "availableActions": [
                "CLONE",
                "DELETE",
                "VIEW_AAG_SETTINGS",
                "EDIT_AAG_SETTINGS",
                "EDIT_ENDPOINT_DEFINITION",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 12,
            "lockVersion": 0
        },
        {
            "createdBy": "aaguser",
            "createDate": "2017-09-06T13:24:14+0000",
            "updateDate": "2017-09-06T13:24:14+0000",
            "updatedBy": "aaguser",
            "apiEndPointVersionId": 320179,
            "basePath": "/aag/automation",
            "description": null,
            "basedOn": 1,
            "stagingStatus": null,
            "productionStatus": null,
            "stagingDate": null,
            "productionDate": null,
            "isVersionLocked": false,
            "availableActions": [
                "CLONE",
                "DELETE",
                "VIEW_AAG_SETTINGS",
                "EDIT_AAG_SETTINGS",
                "EDIT_ENDPOINT_DEFINITION",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "versionNumber": 13,
            "lockVersion": 0
        }
    ]
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

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

The response’s apiVersions array features all versions of the requested endpoint.

Get a Version Summary

This operation returns a summary for a specific endpoint version. The summary is for purely informational purposes, and the response of this operation should not be used in the corresponding Modify a Version PUT request. For the PUT request, use the response object of Get a Version.

GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}

Sample: /api-definitions/v2/endpoints/12892/versions/1

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.

Status 200 application/json

Response Body:

{
    "apiEndPointVersionId": 1941,
    "versionNumber": 1,
    "stagingStatus": "ACTIVE",
    "productionStatus": "ACTIVE",
    "apiResourceNames": [
        "Accounts, Marketing, Billing"
    ],
    "apiEndPointHosts": [
        "api-service.example.com"
    ],
    "apiCategoryIds": [
        601
    ],
    "description": "Provides information about membership benefits and available services.",
    "basePath": "/api-basepath",
    "availableActions": [
        "CLONE_VERSION",
        "CLONE_ENDPOINT",
        "DELETE",
        "RESOURCES",
        "COMPARE_ENDPOINT",
        "COMPARE_RESOURCE_PURPOSES",
        "EDIT_ENDPOINT_DEFINITION",
        "ACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION"
    ]
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Make a GET request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}.

The response object shows the summary information for the requested endpoint version.

Modify a Version

This operation updates details about an endpoint version that has never been activated on the staging or production network. Note that the corresponding Get a Version that you run for this operation as described in STEPS has a different endpoint URL.

PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}

Sample: /api-definitions/v2/endpoints/12892/versions/1

Content-Type: application/json

Request Body:

{
    "createdBy": "joe1",
    "createDate": "2017-11-17T19:27:07+0000",
    "updateDate": "2017-11-17T19:27:07+0000",
    "updatedBy": "joe1",
    "apiEndPointId": 314252,
    "apiEndPointName": "Membership Benefits",
    "description": "Provides information about membership benefits and available services.",
    "basePath": "/api/v2",
    "apiEndPointScheme": "http/https",
    "consumeType": "any",
    "groupId": 44681,
    "versionNumber": 1,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "stagingVersion": {
        "versionNumber": null,
        "status": null
    },
    "productionVersion": {
        "versionNumber": null,
        "status": null
    },
    "protectedByApiKey": false,
    "apiEndPointHosts": [
        "api-service.example.com"
    ],
    "apiCategoryIds": [
        161
    ],
    "contractId": "3-13H55B5",
    "securityScheme": {
        "securitySchemeType": "apikey",
        "securitySchemeDetail": {
            "apiKeyLocation": "header",
            "apiKeyName": "header-101"
        }
    },
    "akamaiSecurityRestrictions": {
        "MAX_JSONXML_ELEMENT": 1032,
        "MAX_ELEMENT_NAME_LENGTH": 256,
        "MAX_DOC_DEPTH": 64,
        "POSITIVE_SECURITY_ENABLED": 1,
        "MAX_STRING_LENGTH": 8192,
        "MAX_BODY_SIZE": 61056,
        "MAX_INTEGER_VALUE": 9999
    },
    "stagingStatus": null,
    "productionStatus": null,
    "apiResources": [
        {
            "apiResourceId": 765432,
            "apiResourceName": "cloud security",
            "resourcePath": "/resources/{resourceId}",
            "description": "resource description",
            "apiResourceMethods": [
                {
                    "apiResourceMethodId": 54362,
                    "apiResourceMethod": "GET",
                    "apiParameters": [
                        {
                            "apiParameterId": 23245,
                            "apiParameterRequired": true,
                            "apiParameterName": "endpoint-id",
                            "apiParameterLocation": "path",
                            "apiParameterType": "integer",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": {
                                "rangeRestriction": {
                                    "rangeMin": 6,
                                    "rangeMax": 15
                                }
                            }
                        },
                        {
                            "apiParameterId": 43212,
                            "apiParameterRequired": true,
                            "apiParameterName": "resourceId",
                            "apiParameterLocation": "path",
                            "apiParameterType": "string",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null
                        }
                    ]
                },
                {
                    "apiResourceMethodId": 43245,
                    "apiResourceMethod": "POST",
                    "apiParameters": [
                        {
                            "apiParameterId": 54353,
                            "apiParameterRequired": true,
                            "apiParameterName": "endpoint-id",
                            "apiParameterLocation": "path",
                            "apiParameterType": "integer",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null
                        },
                        {
                            "apiParameterId": 32314,
                            "apiParameterRequired": true,
                            "apiParameterName": "resourceId",
                            "apiParameterLocation": "path",
                            "apiParameterType": "string",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": {
                                "lengthRestriction": {
                                    "lengthMax": 15,
                                    "lengthMin": 6
                                }
                            }
                        },
                        {
                            "apiParameterId": 32454,
                            "apiParameterRequired": true,
                            "apiParameterName": "post-body",
                            "apiParameterLocation": "body",
                            "apiParameterType": "json/xml",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null,
                            "apiChildParameters": [
                                {
                                    "apiParameterId": 32456,
                                    "apiParameterRequired": true,
                                    "apiParameterName": "id",
                                    "apiParameterLocation": "body",
                                    "apiParameterType": "integer",
                                    "apiParameterNotes": null,
                                    "array": false,
                                    "apiParameterRestriction": {
                                        "rangeRestriction": {
                                            "rangeMin": 6,
                                            "rangeMax": 15
                                        },
                                        "xmlConversionRule": {
                                            "name": null,
                                            "prefix": "idx",
                                            "namespace": "https://www.abc.com/schema/xap.xsd",
                                            "attribute": false,
                                            "wrapped": false
                                        }
                                    }
                                },
                                {
                                    "apiParameterId": 32124,
                                    "apiParameterRequired": true,
                                    "apiParameterName": "name",
                                    "apiParameterLocation": "body",
                                    "apiParameterType": "String",
                                    "apiParameterNotes": null,
                                    "array": false,
                                    "apiParameterRestriction": null
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "lockVersion": 1
}
Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.

Status 200 application/json

Response Body:

{
    "createdBy": "joe1",
    "createDate": "2017-11-17T19:27:07+0000",
    "updateDate": "2017-11-17T19:27:27+0000",
    "updatedBy": "joe1",
    "apiEndPointId": 314252,
    "apiEndPointName": "Membership Benefits",
    "description": "Provides information about membership benefits and available services.",
    "basePath": "/api/v2",
    "apiEndPointScheme": "http/https",
    "consumeType": "any",
    "groupId": 44681,
    "versionNumber": 1,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "stagingVersion": {
        "versionNumber": null,
        "status": null
    },
    "productionVersion": {
        "versionNumber": null,
        "status": null
    },
    "protectedByApiKey": false,
    "apiEndPointHosts": [
        "api-service.example.com"
    ],
    "apiCategoryIds": [
        161
    ],
    "contractId": "3-13H55B5",
    "securityScheme": {
        "securitySchemeType": "apikey",
        "securitySchemeDetail": {
            "apiKeyLocation": "header",
            "apiKeyName": "header-101"
        }
    },
    "akamaiSecurityRestrictions": {
        "MAX_JSONXML_ELEMENT": 1032,
        "MAX_ELEMENT_NAME_LENGTH": 256,
        "MAX_DOC_DEPTH": 64,
        "POSITIVE_SECURITY_ENABLED": 1,
        "MAX_STRING_LENGTH": 8192,
        "MAX_BODY_SIZE": 61056,
        "MAX_INTEGER_VALUE": 9999
    },
    "stagingStatus": null,
    "productionStatus": null,
    "apiResources": [
        {
            "apiResourceId": 765432,
            "apiResourceName": "cloud security",
            "resourcePath": "/resources/{resourceId}",
            "description": "resource description",
            "apiResourceMethods": [
                {
                    "apiResourceMethodId": 54362,
                    "apiResourceMethod": "GET",
                    "apiParameters": [
                        {
                            "apiParameterId": 23245,
                            "apiParameterRequired": true,
                            "apiParameterName": "endpoint-id",
                            "apiParameterLocation": "path",
                            "apiParameterType": "integer",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": {
                                "rangeRestriction": {
                                    "rangeMin": 6,
                                    "rangeMax": 15
                                }
                            }
                        },
                        {
                            "apiParameterId": 43212,
                            "apiParameterRequired": true,
                            "apiParameterName": "resourceId",
                            "apiParameterLocation": "path",
                            "apiParameterType": "string",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null
                        }
                    ]
                },
                {
                    "apiResourceMethodId": 43245,
                    "apiResourceMethod": "POST",
                    "apiParameters": [
                        {
                            "apiParameterId": 54353,
                            "apiParameterRequired": true,
                            "apiParameterName": "endpoint-id",
                            "apiParameterLocation": "path",
                            "apiParameterType": "integer",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null
                        },
                        {
                            "apiParameterId": 32314,
                            "apiParameterRequired": true,
                            "apiParameterName": "resourceId",
                            "apiParameterLocation": "path",
                            "apiParameterType": "string",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": {
                                "lengthRestriction": {
                                    "lengthMax": 15,
                                    "lengthMin": 6
                                }
                            }
                        },
                        {
                            "apiParameterId": 32454,
                            "apiParameterRequired": true,
                            "apiParameterName": "post-body",
                            "apiParameterLocation": "body",
                            "apiParameterType": "json/xml",
                            "apiParameterNotes": null,
                            "array": false,
                            "apiParameterRestriction": null,
                            "apiChildParameters": [
                                {
                                    "apiParameterId": 32456,
                                    "apiParameterRequired": true,
                                    "apiParameterName": "id",
                                    "apiParameterLocation": "body",
                                    "apiParameterType": "integer",
                                    "apiParameterNotes": null,
                                    "array": false,
                                    "apiParameterRestriction": {
                                        "rangeRestriction": {
                                            "rangeMin": 6,
                                            "rangeMax": 15
                                        },
                                        "xmlConversionRule": {
                                            "name": null,
                                            "prefix": "idx",
                                            "namespace": "https://www.abc.com/schema/xap.xsd",
                                            "attribute": false,
                                            "wrapped": false
                                        }
                                    }
                                },
                                {
                                    "apiParameterId": 32124,
                                    "apiParameterRequired": true,
                                    "apiParameterName": "name",
                                    "apiParameterLocation": "body",
                                    "apiParameterType": "String",
                                    "apiParameterNotes": null,
                                    "array": false,
                                    "apiParameterRestriction": null
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "lockVersion": 2
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Run the Get a Version operation for the complete representation of the object.

  6. Modify the returned object.

  7. PUT the object to the following URL: /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}.

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

Remove a Version

This operation removes an endpoint version from Akamai API Gateway if the version has never been activated on the staging or production network. This is a soft delete operation that preserves the version’s information, such as its number, in the database. The system assigns a permanent number to each version that you create in Akamai API Gateway.

DELETE /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}

Sample: /api-definitions/v2/endpoints/12892/versions/1

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.

Status 204

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

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Make a DELETE request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}.

A 204 response confirms the version has been deleted.

Update an Endpoint from an API Definition File

This operation imports an API definition file with details about an endpoint. You either upload, or specify a URL to a Swagger 2.0 or RAML 0.8 file to import endpoint details. Unlike Create an Endpoint from an API Definition File, this operation does not create a new endpoint, but updates details of an already existing endpoint. It requires you to submit a multipart/form-data request with the form parameters listed on the Parameters tab. For details on multipart/form-data requests, see RFC 2388. Once you submit the multipart/form-data request, to finish modifying the endpoint version, you need to take the response data and submit it as a request to the Modify a Version operation.

POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/file

Sample: /api-definitions/v2/endpoints/12892/versions/1/file

Content-Type: multipart/form-data

See Parameters for details on upload content.

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.
Form Parameters
importFileFormat Enumeration raml The format of the API definition, 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 definition file.
root String api_descriptor.raml If the import file is a ZIP archive, this identifies the API definition’s filename within the archive.

Status 200 application/json

Response Body:

{
    "createdBy": "joe1",
    "createDate": "2017-09-06T16:15:44+0000",
    "updateDate": "2017-09-06T16:15:44+0000",
    "updatedBy": "joe1",
    "apiEndPointId": 289157,
    "apiEndPointName": "Membership Benefits",
    "description": null,
    "basePath": "/api/v2",
    "apiEndPointScheme": null,
    "consumeType": "any",
    "groupId": 44681,
    "versionNumber": 1,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "protectedByApiKey": false,
    "stagingVersion": {
        "versionNumber": null,
        "status": null
    },
    "productionVersion": {
        "versionNumber": null,
        "status": null
    },
    "apiEndPointHosts": [
        "api-service.example.com"
    ],
    "apiCategoryIds": [
        1123
    ],
    "contractId": "3-13H55B5",
    "securityScheme": {
        "securitySchemeType": "apikey",
        "securitySchemeDetail": {
            "apiKeyLocation": "header",
            "apiKeyName": "header-api"
        }
    },
    "akamaiSecurityRestrictions": {
        "MAX_JSONXML_ELEMENT": 10,
        "MAX_ELEMENT_NAME_LENGTH": 256,
        "POSITIVE_SECURITY_ENABLED": 1,
        "MAX_DOC_DEPTH": 64,
        "MAX_BODY_SIZE": 23433454,
        "MAX_STRING_LENGTH": 999999999999,
        "MAX_INTEGER_VALUE": 999999999
    },
    "stagingStatus": null,
    "productionStatus": null,
    "apiResources": [
        {
            "createdBy": "joe1",
            "createDate": "2017-09-06T16:15:45+0000",
            "updateDate": "2017-09-06T16:15:45+0000",
            "updatedBy": "joe1",
            "apiResourceId": 12943,
            "apiResourceName": "Billing",
            "resourcePath": "/billing",
            "description": "Billing data",
            "link": null,
            "apiResourceClonedFromId": null,
            "apiResourceLogicId": 14180,
            "apiResourceMethods": [
                {
                    "apiResourceMethodId": 30135,
                    "apiResourceMethod": "GET",
                    "apiParameters": [
                        {
                            "apiParameterId": 35545,
                            "apiParameterRequired": true,
                            "apiParameterName": "param1",
                            "apiParameterLocation": "header",
                            "apiParameterType": "integer",
                            "array": false,
                            "apiParamLogicId": 32645,
                            "apiResourceMethParamId": 19682,
                            "apiChildParameters": [],
                            "apiParameterRestriction": {
                                "lengthRestriction": null,
                                "rangeRestriction": {
                                    "rangeMin": null,
                                    "rangeMax": null
                                },
                                "numberRangeRestriction": null,
                                "arrayRestriction": null,
                                "xmlConversionRule": null
                            },
                            "apiParameterNotes": null
                        },
                        {
                            "apiParameterId": 35546,
                            "apiParameterRequired": false,
                            "apiParameterName": "param-2",
                            "apiParameterLocation": "cookie",
                            "apiParameterType": "number",
                            "array": false,
                            "apiParamLogicId": 32646,
                            "apiResourceMethParamId": 19683,
                            "apiChildParameters": [],
                            "apiParameterRestriction": {
                                "lengthRestriction": null,
                                "rangeRestriction": null,
                                "numberRangeRestriction": {
                                    "numberRangeMin": null,
                                    "numberRangeMax": 999999.0
                                },
                                "arrayRestriction": null,
                                "xmlConversionRule": null
                            },
                            "apiParameterNotes": null
                        }
                    ],
                    "apiResourceMethodLogicId": 25615
                },
                {
                    "apiResourceMethodId": 30136,
                    "apiResourceMethod": "POST",
                    "apiParameters": [
                        {
                            "apiParameterId": 35547,
                            "apiParameterRequired": false,
                            "apiParameterName": "body-param",
                            "apiParameterLocation": "body",
                            "apiParameterType": "json/xml",
                            "array": false,
                            "apiParamLogicId": 32647,
                            "apiResourceMethParamId": 19684,
                            "apiChildParameters": [
                                {
                                    "apiParameterId": 35548,
                                    "apiParameterRequired": true,
                                    "apiParameterName": "root",
                                    "apiParameterLocation": null,
                                    "apiParameterType": "json/xml",
                                    "array": false,
                                    "apiParamLogicId": 32648,
                                    "apiResourceMethParamId": null,
                                    "apiChildParameters": [
                                        {
                                            "apiParameterId": 35549,
                                            "apiParameterRequired": false,
                                            "apiParameterName": "param1",
                                            "apiParameterLocation": null,
                                            "apiParameterType": "integer",
                                            "array": false,
                                            "apiParamLogicId": 32649,
                                            "apiResourceMethParamId": null,
                                            "apiChildParameters": [],
                                            "apiParameterRestriction": {
                                                "lengthRestriction": null,
                                                "rangeRestriction": {
                                                    "rangeMin": 1,
                                                    "rangeMax": 999
                                                },
                                                "numberRangeRestriction": null,
                                                "arrayRestriction": null,
                                                "xmlConversionRule": null
                                            },
                                            "apiParameterNotes": null
                                        },
                                        {
                                            "apiParameterId": 35550,
                                            "apiParameterRequired": false,
                                            "apiParameterName": "param-2",
                                            "apiParameterLocation": null,
                                            "apiParameterType": "number",
                                            "array": false,
                                            "apiParamLogicId": 32650,
                                            "apiResourceMethParamId": null,
                                            "apiChildParameters": [],
                                            "apiParameterRestriction": {
                                                "lengthRestriction": null,
                                                "rangeRestriction": null,
                                                "numberRangeRestriction": {
                                                    "numberRangeMin": -999.0,
                                                    "numberRangeMax": 999.0
                                                },
                                                "arrayRestriction": null,
                                                "xmlConversionRule": null
                                            },
                                            "apiParameterNotes": null
                                        }
                                    ],
                                    "apiParameterRestriction": null,
                                    "apiParameterNotes": null
                                }
                            ],
                            "apiParameterRestriction": null,
                            "apiParameterNotes": null
                        }
                    ],
                    "apiResourceMethodLogicId": 25616
                }
            ],
            "lockVersion": 1
        }
    ],
    "lockVersion": 1
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Prepare an API definition file and set the importFileFormat to raml or swagger.

  6. Assign the filename as the importFile.

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

  8. Optionally make the definition or archive file available on the web at an importUrl.

  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/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/file.

  11. Perform the Modify a Version operation using the returned Endpoint object for the PUT request.

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

Get a Version

This operation returns an endpoint version. Note that you can use the response object of this operation when you want to modify an endpoint version via Modify a Version.

GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources-detail

Sample: /api-definitions/v2/endpoints/12892/versions/1/resources-detail

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.

Status 200 application/json

Response Body:

{
    "createdBy": "joe1",
    "createDate": "2017-09-06T16:15:44+0000",
    "updateDate": "2017-09-06T16:15:44+0000",
    "updatedBy": "joe1",
    "apiEndPointId": 289157,
    "apiEndPointName": "Membership Benefits",
    "description": null,
    "basePath": "/api/v2",
    "apiEndPointScheme": null,
    "consumeType": "any",
    "groupId": 44681,
    "versionNumber": 1,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "protectedByApiKey": false,
    "stagingVersion": {
        "versionNumber": null,
        "status": null
    },
    "productionVersion": {
        "versionNumber": null,
        "status": null
    },
    "apiEndPointHosts": [
        "api-service.example.com"
    ],
    "apiCategoryIds": [
        1123
    ],
    "contractId": "3-13H55B5",
    "securityScheme": {
        "securitySchemeType": "apikey",
        "securitySchemeDetail": {
            "apiKeyLocation": "header",
            "apiKeyName": "header-api"
        }
    },
    "akamaiSecurityRestrictions": {
        "MAX_JSONXML_ELEMENT": 10,
        "MAX_ELEMENT_NAME_LENGTH": 256,
        "POSITIVE_SECURITY_ENABLED": 1,
        "MAX_DOC_DEPTH": 64,
        "MAX_BODY_SIZE": 23433454,
        "MAX_STRING_LENGTH": 999999999999,
        "MAX_INTEGER_VALUE": 999999999
    },
    "stagingStatus": null,
    "productionStatus": null,
    "apiResources": [
        {
            "createdBy": "joe1",
            "createDate": "2017-09-06T16:15:45+0000",
            "updateDate": "2017-09-06T16:15:45+0000",
            "updatedBy": "joe1",
            "apiResourceId": 12943,
            "apiResourceName": "Billing",
            "resourcePath": "/billing",
            "description": "Billing data",
            "link": null,
            "apiResourceClonedFromId": null,
            "apiResourceLogicId": 14180,
            "apiResourceMethods": [
                {
                    "apiResourceMethodId": 30135,
                    "apiResourceMethod": "GET",
                    "apiParameters": [
                        {
                            "apiParameterId": 35545,
                            "apiParameterRequired": true,
                            "apiParameterName": "param1",
                            "apiParameterLocation": "header",
                            "apiParameterType": "integer",
                            "array": false,
                            "apiParamLogicId": 32645,
                            "apiResourceMethParamId": 19682,
                            "apiChildParameters": [],
                            "apiParameterRestriction": {
                                "lengthRestriction": null,
                                "rangeRestriction": {
                                    "rangeMin": null,
                                    "rangeMax": null
                                },
                                "numberRangeRestriction": null,
                                "arrayRestriction": null,
                                "xmlConversionRule": null
                            },
                            "apiParameterNotes": null
                        },
                        {
                            "apiParameterId": 35546,
                            "apiParameterRequired": false,
                            "apiParameterName": "param-2",
                            "apiParameterLocation": "cookie",
                            "apiParameterType": "number",
                            "array": false,
                            "apiParamLogicId": 32646,
                            "apiResourceMethParamId": 19683,
                            "apiChildParameters": [],
                            "apiParameterRestriction": {
                                "lengthRestriction": null,
                                "rangeRestriction": null,
                                "numberRangeRestriction": {
                                    "numberRangeMin": null,
                                    "numberRangeMax": 999999.0
                                },
                                "arrayRestriction": null,
                                "xmlConversionRule": null
                            },
                            "apiParameterNotes": null
                        }
                    ],
                    "apiResourceMethodLogicId": 25615
                },
                {
                    "apiResourceMethodId": 30136,
                    "apiResourceMethod": "POST",
                    "apiParameters": [
                        {
                            "apiParameterId": 35547,
                            "apiParameterRequired": false,
                            "apiParameterName": "body-param",
                            "apiParameterLocation": "body",
                            "apiParameterType": "json/xml",
                            "array": false,
                            "apiParamLogicId": 32647,
                            "apiResourceMethParamId": 19684,
                            "apiChildParameters": [
                                {
                                    "apiParameterId": 35548,
                                    "apiParameterRequired": true,
                                    "apiParameterName": "root",
                                    "apiParameterLocation": null,
                                    "apiParameterType": "json/xml",
                                    "array": false,
                                    "apiParamLogicId": 32648,
                                    "apiResourceMethParamId": null,
                                    "apiChildParameters": [
                                        {
                                            "apiParameterId": 35549,
                                            "apiParameterRequired": false,
                                            "apiParameterName": "param1",
                                            "apiParameterLocation": null,
                                            "apiParameterType": "integer",
                                            "array": false,
                                            "apiParamLogicId": 32649,
                                            "apiResourceMethParamId": null,
                                            "apiChildParameters": [],
                                            "apiParameterRestriction": {
                                                "lengthRestriction": null,
                                                "rangeRestriction": {
                                                    "rangeMin": 1,
                                                    "rangeMax": 999
                                                },
                                                "numberRangeRestriction": null,
                                                "arrayRestriction": null,
                                                "xmlConversionRule": null
                                            },
                                            "apiParameterNotes": null
                                        },
                                        {
                                            "apiParameterId": 35550,
                                            "apiParameterRequired": false,
                                            "apiParameterName": "param-2",
                                            "apiParameterLocation": null,
                                            "apiParameterType": "number",
                                            "array": false,
                                            "apiParamLogicId": 32650,
                                            "apiResourceMethParamId": null,
                                            "apiChildParameters": [],
                                            "apiParameterRestriction": {
                                                "lengthRestriction": null,
                                                "rangeRestriction": null,
                                                "numberRangeRestriction": {
                                                    "numberRangeMin": -999.0,
                                                    "numberRangeMax": 999.0
                                                },
                                                "arrayRestriction": null,
                                                "xmlConversionRule": null
                                            },
                                            "apiParameterNotes": null
                                        }
                                    ],
                                    "apiParameterRestriction": null,
                                    "apiParameterNotes": null
                                }
                            ],
                            "apiParameterRestriction": null,
                            "apiParameterNotes": null
                        }
                    ],
                    "apiResourceMethodLogicId": 25616
                }
            ],
            "lockVersion": 1
        }
    ],
    "lockVersion": 1
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Make a GET request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources-detail.

The response is the requested version of the specified Endpoint object.

Clone a Version

This operation creates a new endpoint version as a clone of an existing version. The system assigns a new number to the version that you clone.

POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/cloneVersion

Sample: /api-definitions/v2/endpoints/12892/versions/1/cloneVersion

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.

Status 200 application/json

Response Body:

{
    "createdBy": "ccare2",
    "createDate": "2017-09-06T16:15:44+0000",
    "updateDate": "2017-09-06T16:15:44+0000",
    "updatedBy": "ccare2",
    "apiEndPointId": 313305,
    "apiEndPointName": "Membership Benefits",
    "description": null,
    "basePath": "/api-basepath",
    "apiEndPointScheme": null,
    "consumeType": "any",
    "groupId": 44680,
    "versionNumber": 2,
    "clonedFromVersion": 1,
    "apiEndPointLocked": false,
    "stagingVersion": {
        "versionNumber": null,
        "status": null
    },
    "productionVersion": {
        "versionNumber": null,
        "status": null
    },
    "apiEndPointHosts": [
        "api-service.example.com"
    ],
    "apiCategoryIds": [
        1123
    ],
    "contractId": "3-13H55B5",
    "securityScheme": {
        "securitySchemeType": "apikey",
        "securitySchemeDetail": {
            "apiKeyLocation": "header",
            "apiKeyName": "header-api"
        }
    },
    "akamaiSecurityRestrictions": {
        "MAX_JSONXML_ELEMENT": 10,
        "MAX_ELEMENT_NAME_LENGTH": 256,
        "POSITIVE_SECURITY_ENABLED": 1,
        "MAX_DOC_DEPTH": 64,
        "MAX_BODY_SIZE": 23433454,
        "MAX_STRING_LENGTH": 999999999999,
        "MAX_INTEGER_VALUE": 999999999
    },
    "stagingStatus": null,
    "productionStatus": null,
    "apiResources": [
        {
            "createdBy": "ccare2",
            "createDate": "2017-09-06T16:15:45+0000",
            "updateDate": "2017-09-06T16:15:45+0000",
            "updatedBy": "ccare2",
            "apiResourceId": 12943,
            "apiResourceName": "Billing",
            "resourcePath": "/billing",
            "description": "Billing data",
            "link": null,
            "apiResourceClonedFromId": null,
            "apiResourceLogicId": 14180,
            "apiResourceMethods": [
                {
                    "apiResourceMethodId": 30135,
                    "apiResourceMethod": "GET",
                    "apiParameters": [
                        {
                            "apiParameterId": 35545,
                            "apiParameterRequired": true,
                            "apiParameterName": "param1",
                            "apiParameterLocation": "header",
                            "apiParameterType": "integer",
                            "array": false,
                            "apiParamLogicId": 32645,
                            "apiResourceMethParamId": 19682,
                            "apiChildParameters": [],
                            "apiParameterRestriction": {
                                "lengthRestriction": null,
                                "rangeRestriction": {
                                    "rangeMin": null,
                                    "rangeMax": null
                                },
                                "numberRangeRestriction": null,
                                "arrayRestriction": null,
                                "xmlConversionRule": null
                            },
                            "apiParameterNotes": null
                        },
                        {
                            "apiParameterId": 35546,
                            "apiParameterRequired": false,
                            "apiParameterName": "param-2",
                            "apiParameterLocation": "cookie",
                            "apiParameterType": "number",
                            "array": false,
                            "apiParamLogicId": 32646,
                            "apiResourceMethParamId": 19683,
                            "apiChildParameters": [],
                            "apiParameterRestriction": {
                                "lengthRestriction": null,
                                "rangeRestriction": null,
                                "numberRangeRestriction": {
                                    "numberRangeMin": null,
                                    "numberRangeMax": 999999.0
                                },
                                "arrayRestriction": null,
                                "xmlConversionRule": null
                            },
                            "apiParameterNotes": null
                        }
                    ],
                    "apiResourceMethodLogicId": 25615
                },
                {
                    "apiResourceMethodId": 30136,
                    "apiResourceMethod": "POST",
                    "apiParameters": [
                        {
                            "apiParameterId": 35547,
                            "apiParameterRequired": false,
                            "apiParameterName": "body-param",
                            "apiParameterLocation": "body",
                            "apiParameterType": "json/xml",
                            "array": false,
                            "apiParamLogicId": 32647,
                            "apiResourceMethParamId": 19684,
                            "apiChildParameters": [
                                {
                                    "apiParameterId": 35548,
                                    "apiParameterRequired": true,
                                    "apiParameterName": "root",
                                    "apiParameterLocation": null,
                                    "apiParameterType": "json/xml",
                                    "array": false,
                                    "apiParamLogicId": 32648,
                                    "apiResourceMethParamId": null,
                                    "apiChildParameters": [
                                        {
                                            "apiParameterId": 35549,
                                            "apiParameterRequired": false,
                                            "apiParameterName": "param1",
                                            "apiParameterLocation": null,
                                            "apiParameterType": "integer",
                                            "array": false,
                                            "apiParamLogicId": 32649,
                                            "apiResourceMethParamId": null,
                                            "apiChildParameters": [],
                                            "apiParameterRestriction": {
                                                "lengthRestriction": null,
                                                "rangeRestriction": {
                                                    "rangeMin": 1,
                                                    "rangeMax": 999
                                                },
                                                "numberRangeRestriction": null,
                                                "arrayRestriction": null,
                                                "xmlConversionRule": null
                                            },
                                            "apiParameterNotes": null
                                        },
                                        {
                                            "apiParameterId": 35550,
                                            "apiParameterRequired": false,
                                            "apiParameterName": "param-2",
                                            "apiParameterLocation": null,
                                            "apiParameterType": "number",
                                            "array": false,
                                            "apiParamLogicId": 32650,
                                            "apiResourceMethParamId": null,
                                            "apiChildParameters": [],
                                            "apiParameterRestriction": {
                                                "lengthRestriction": null,
                                                "rangeRestriction": null,
                                                "numberRangeRestriction": {
                                                    "numberRangeMin": -999.0,
                                                    "numberRangeMax": 999.0
                                                },
                                                "arrayRestriction": null,
                                                "xmlConversionRule": null
                                            },
                                            "apiParameterNotes": null
                                        }
                                    ],
                                    "apiParameterRestriction": null,
                                    "apiParameterNotes": null
                                }
                            ],
                            "apiParameterRestriction": null,
                            "apiParameterNotes": null
                        }
                    ],
                    "apiResourceMethodLogicId": 25616
                }
            ],
            "lockVersion": 2
        }
    ],
    "lockVersion": 2
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Make a POST request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/cloneVersion.

The response reflects back the cloned version of the specified Endpoint object.

Activate a Version

This operation activates an endpoint version on the network of your choice, either staging or production. If another version of the endpoint is already active on the specified network, that version becomes automatically deactivated and the newly activated version takes its place. If an active version of another endpoint has the same hostnames assigned as the version you activate, the system automatically deactivates the version with conflicting hostnames, creates a new version of the impacted endpoint, migrates the non-conflicting hostnames and other API details to the new version, and activates the new version.

POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/activate

Sample: /api-definitions/v2/endpoints/12892/versions/1/activate

Content-Type: application/json

Request Body:

{
    "networks": [
        "STAGING",
        "PRODUCTION"
    ],
    "notificationRecipients": [
        "joe@example.com"
    ],
    "notes": "Activating endpoint in both networks."
}
Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.

Status 200 application/problem+json

Response Body:

{
    "networks": [
        "STAGING",
        "PRODUCTION"
    ],
    "notificationRecipients": [
        "joe@example.com"
    ],
    "notes": "Activating endpoint in both networks."
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Build an Activation object, specifying the networks where you activate the version and the email addresses for the notificationRecipients.

  6. POST the object to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/activate.

A 200 response confirms a successful activation.

Deactivate a Version

This operation deactivates an endpoint version on the network of your choice, either staging or production.

POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/deactivate

Sample: /api-definitions/v2/endpoints/12892/versions/1/deactivate

Content-Type: application/json

Request Body:

{
    "networks": [
        "STAGING",
        "PRODUCTION"
    ],
    "notificationRecipients": [
        "joe@example.com"
    ],
    "notes": "Activating endpoint in both networks."
}
Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.

Status 200 application/problem+json

Response Body:

{
    "networks": [
        "STAGING",
        "PRODUCTION"
    ],
    "notificationRecipients": [
        "joe@example.com"
    ],
    "notes": "Activating endpoint in both networks."
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Build an Activation object, specifying the networks where you deactivate the version and the email addresses for the notificationRecipients.

  6. POST the object to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/deactivate.

A 200 response confirms a successful deactivation.

List Resources

This operation lists all resources associated with an endpoint version.

GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources

Sample: /api-definitions/v2/endpoints/12892/versions/1/resources

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.

Status 200 application/json

Response Body:

[
    {
        "apiResourceId": 22605,
        "apiResourceName": "Pet store",
        "resourcePath": "/pet/store",
        "description": "pet store resource",
        "link": null,
        "apiResourceClonedFromId": null,
        "apiResourceLogicId": 23782,
        "private": false,
        "createdBy": "rsmith",
        "createDate": "2018-02-12T17:32:25+0000",
        "updateDate": "2018-02-12T17:32:25+0000",
        "updatedBy": "rsmith",
        "apiResourceMethods": [
            {
                "apiResourceMethodId": 68519,
                "apiResourceMethod": "GET",
                "apiParameters": [
                    {
                        "apiParameterId": 67249,
                        "apiParameterRequired": true,
                        "apiParameterName": "name",
                        "apiParameterLocation": "header",
                        "apiParameterType": "integer",
                        "array": false,
                        "pathParamLocationId": 0,
                        "apiParamLogicId": 62389,
                        "apiResourceMethParamId": 50526,
                        "apiChildParameters": [],
                        "apiParameterRestriction": {
                            "lengthRestriction": null,
                            "rangeRestriction": {
                                "rangeMin": 1,
                                "rangeMax": 99999
                            },
                            "numberRangeRestriction": null,
                            "arrayRestriction": null,
                            "xmlConversionRule": null
                        },
                        "apiParameterNotes": null
                    }
                ],
                "apiResourceMethodLogicId": 63379
            },
            {
                "apiResourceMethodId": 68520,
                "apiResourceMethod": "POST",
                "apiParameters": [
                    {
                        "apiParameterId": 67250,
                        "apiParameterRequired": true,
                        "apiParameterName": "pet-body",
                        "apiParameterLocation": "body",
                        "apiParameterType": "json/xml",
                        "array": false,
                        "pathParamLocationId": 0,
                        "apiParamLogicId": 62390,
                        "apiResourceMethParamId": 50527,
                        "apiChildParameters": [
                            {
                                "apiParameterId": 67251,
                                "apiParameterRequired": true,
                                "apiParameterName": "id",
                                "apiParameterLocation": "body",
                                "apiParameterType": "integer",
                                "array": false,
                                "pathParamLocationId": 0,
                                "apiParamLogicId": 62391,
                                "apiResourceMethParamId": null,
                                "apiChildParameters": [],
                                "apiParameterRestriction": {
                                    "lengthRestriction": null,
                                    "rangeRestriction": {
                                        "rangeMin": 1,
                                        "rangeMax": 9999
                                    },
                                    "numberRangeRestriction": null,
                                    "arrayRestriction": null,
                                    "xmlConversionRule": null
                                },
                                "apiParameterNotes": null
                            },
                            {
                                "apiParameterId": 67252,
                                "apiParameterRequired": false,
                                "apiParameterName": "name",
                                "apiParameterLocation": "body",
                                "apiParameterType": "string",
                                "array": false,
                                "pathParamLocationId": 0,
                                "apiParamLogicId": 62392,
                                "apiResourceMethParamId": null,
                                "apiChildParameters": [],
                                "apiParameterRestriction": {
                                    "lengthRestriction": {
                                        "lengthMax": 128,
                                        "lengthMin": null
                                    },
                                    "rangeRestriction": null,
                                    "numberRangeRestriction": null,
                                    "arrayRestriction": null,
                                    "xmlConversionRule": null
                                },
                                "apiParameterNotes": null
                            }
                        ],
                        "apiParameterRestriction": null,
                        "apiParameterNotes": null
                    }
                ],
                "apiResourceMethodLogicId": 63380
            }
        ],
        "lockVersion": 0
    },
    {
        "apiResourceId": 22606,
        "apiResourceName": "Store Inventory",
        "resourcePath": "/store/inventory",
        "description": "Store inventory details",
        "link": null,
        "apiResourceClonedFromId": null,
        "apiResourceLogicId": 23783,
        "private": false,
        "createdBy": "rsmith",
        "createDate": "2018-02-12T17:32:25+0000",
        "updateDate": "2018-02-12T17:32:25+0000",
        "updatedBy": "rsmith",
        "apiResourceMethods": [
            {
                "apiResourceMethodId": 68521,
                "apiResourceMethod": "GET",
                "apiParameters": [
                    {
                        "apiParameterId": 67253,
                        "apiParameterRequired": true,
                        "apiParameterName": "store-id",
                        "apiParameterLocation": "query",
                        "apiParameterType": "integer",
                        "array": false,
                        "pathParamLocationId": 0,
                        "apiParamLogicId": 62393,
                        "apiResourceMethParamId": 50528,
                        "apiChildParameters": [],
                        "apiParameterRestriction": {
                            "lengthRestriction": null,
                            "rangeRestriction": {
                                "rangeMin": null,
                                "rangeMax": 99999999
                            },
                            "numberRangeRestriction": null,
                            "arrayRestriction": null,
                            "xmlConversionRule": null
                        },
                        "apiParameterNotes": null
                    }
                ],
                "apiResourceMethodLogicId": 63381
            }
        ],
        "lockVersion": 0
    }
]
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Make a GET request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources.

The response is an array of Resource objects.

Create a Resource

This operation creates a resource in an endpoint version. The resource’s full URL (concatenated hostname, basePath, and resourcepath) needs to be unique within the account. You can only create resources for versions that have never been activated on the staging or production network.

POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources

Sample: /api-definitions/v2/endpoints/12892/versions/1/resources

Content-Type: application/json

Request Body:

{
    "apiResourceName": "cloud security",
    "resourcePath": "/resources/{resourceId}",
    "description": "resource description",
    "apiResourceMethods": [
        {
            "apiResourceMethod": "GET",
            "apiParameters": [
                {
                    "apiParameterRequired": true,
                    "apiParameterName": "endpoint-id",
                    "apiParameterLocation": "path",
                    "apiParameterType": "integer",
                    "apiParameterNotes": null,
                    "array": false,
                    "apiParameterRestriction": {
                        "rangeRestriction": {
                            "rangeMin": 6,
                            "rangeMax": 15
                        }
                    }
                },
                {
                    "apiParameterRequired": true,
                    "apiParameterName": "resourceId",
                    "apiParameterLocation": "path",
                    "apiParameterType": "string",
                    "apiParameterNotes": null,
                    "array": false,
                    "apiParameterRestriction": null
                }
            ]
        }
    ]
}
Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.

Status 201 application/json

Headers:

Location: /api-definitions/v2/endpoints/123/versions/1/resources/1234

Response Body:

{
    "apiResourceId": 12893,
    "apiResourceName": "cloud security",
    "resourcePath": "/resources/{resourceId}",
    "description": "resource description",
    "lockVersion": 3,
    "apiResourceClonedFromId": null,
    "apiResourceLogicId": 14180,
    "createdBy": "rsmith",
    "createDate": "2013-10-07T17:41:52+0000",
    "updatedBy": "rsmith",
    "updateDate": "2015-10-07T17:41:52+0000",
    "apiResourceMethods": [
        {
            "apiResourceMethodId": 1902,
            "apiResourceMethod": "GET",
            "apiResourceMethodLogicId": 25615,
            "apiParameters": [
                {
                    "apiParameterId": 9230,
                    "apiParameterRequired": true,
                    "apiParameterName": "endpoint-id",
                    "apiParameterLocation": "path",
                    "apiParameterType": "integer",
                    "apiParameterNotes": null,
                    "apiParamLogicId": 32649,
                    "array": false,
                    "apiParameterRestriction": {
                        "rangeRestriction": {
                            "rangeMin": 6,
                            "rangeMax": 15
                        }
                    }
                },
                {
                    "apiParameterId": 8793,
                    "apiParameterRequired": true,
                    "apiParameterName": "resourceId",
                    "apiParameterLocation": "path",
                    "apiParameterType": "string",
                    "apiParameterNotes": null,
                    "apiParamLogicId": 32650,
                    "array": false,
                    "apiParameterRestriction": null
                }
            ]
        }
    ]
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Build a Resource object, specifying a unique apiResourceName and resourcePath.

  6. POST the object to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources.

The response reflects back the complete Resource object, from which you can store the apiResourceId value. You can access the newly created resource at the URL specified in the Location response header.

Get a Resource

This operation returns a resource within an endpoint version.

GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources/{apiResourceId}

Sample: /api-definitions/v2/endpoints/12892/versions/1/resources/7689

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.
apiResourceId Integer 7689 The unique identifier for the resource.

Status 200 application/json

Response Body:

{
    "apiResourceId": 12893,
    "apiResourceName": "cloud security",
    "resourcePath": "/resources/{resourceId}",
    "description": "resource description",
    "lockVersion": 3,
    "apiResourceClonedFromId": null,
    "apiResourceLogicId": 14180,
    "createdBy": "rsmith",
    "createDate": "2013-10-07T17:41:52+0000",
    "updatedBy": "rsmith",
    "updateDate": "2015-10-07T17:41:52+0000",
    "apiResourceMethods": [
        {
            "apiResourceMethodId": 1902,
            "apiResourceMethod": "GET",
            "apiResourceMethodLogicId": 25615,
            "apiParameters": [
                {
                    "apiParameterId": 9230,
                    "apiParameterRequired": true,
                    "apiParameterName": "endpoint-id",
                    "apiParameterLocation": "path",
                    "apiParameterType": "integer",
                    "apiParameterNotes": null,
                    "apiParamLogicId": 32649,
                    "array": false,
                    "apiParameterRestriction": {
                        "rangeRestriction": {
                            "rangeMin": 6,
                            "rangeMax": 15
                        }
                    }
                },
                {
                    "apiParameterId": 8793,
                    "apiParameterRequired": true,
                    "apiParameterName": "resourceId",
                    "apiParameterLocation": "path",
                    "apiParameterType": "string",
                    "apiParameterNotes": null,
                    "apiParamLogicId": 32650,
                    "array": false,
                    "apiParameterRestriction": null
                }
            ]
        }
    ]
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

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

  6. Pick the appropriate resource from the returned array and store its apiResourceId value.

  7. Make a GET request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources/{apiResourceId}.

The response is a Resource object.

Modify a Resource

This operation updates a resource within an endpoint version. You can edit information about a resource, the methods, and the parameters associated with a resource. You can only modify resources associated with versions that have never been activated on the staging or production network.

PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources/{apiResourceId}

Sample: /api-definitions/v2/endpoints/12892/versions/1/resources/7689

Content-Type: application/json

Request Body:

{
    "apiResourceId": 12893,
    "apiResourceName": "cloud security",
    "resourcePath": "/resources/{resourceId}",
    "description": "resource description",
    "lockVersion": 3,
    "apiResourceClonedFromId": null,
    "apiResourceLogicId": 14180,
    "createdBy": "rsmith",
    "createDate": "2013-10-07T17:41:52+0000",
    "updatedBy": "rsmith",
    "updateDate": "2015-10-07T17:41:52+0000",
    "apiResourceMethods": [
        {
            "apiResourceMethodId": 1902,
            "apiResourceMethod": "GET",
            "apiResourceMethodLogicId": 25615,
            "apiParameters": [
                {
                    "apiParameterId": 9230,
                    "apiParameterRequired": true,
                    "apiParameterName": "endpoint-id",
                    "apiParameterLocation": "path",
                    "apiParameterType": "integer",
                    "apiParameterNotes": null,
                    "apiParamLogicId": 32649,
                    "array": false,
                    "apiParameterRestriction": {
                        "rangeRestriction": {
                            "rangeMin": 6,
                            "rangeMax": 15
                        }
                    }
                },
                {
                    "apiParameterId": 8793,
                    "apiParameterRequired": true,
                    "apiParameterName": "resourceId",
                    "apiParameterLocation": "path",
                    "apiParameterType": "string",
                    "apiParameterNotes": null,
                    "apiParamLogicId": 32650,
                    "array": false,
                    "apiParameterRestriction": null
                }
            ]
        }
    ]
}
Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.
apiResourceId Integer 7689 The unique identifier for the resource.

Status 200 application/json

Response Body:

{
    "apiResourceId": 12893,
    "apiResourceName": "cloud security",
    "resourcePath": "/resources/{resourceId}",
    "description": "resource description",
    "lockVersion": 3,
    "apiResourceClonedFromId": null,
    "apiResourceLogicId": 14180,
    "createdBy": "rsmith",
    "createDate": "2013-10-07T17:41:52+0000",
    "updatedBy": "rsmith",
    "updateDate": "2015-10-07T17:41:52+0000",
    "apiResourceMethods": [
        {
            "apiResourceMethodId": 1902,
            "apiResourceMethod": "GET",
            "apiResourceMethodLogicId": 25615,
            "apiParameters": [
                {
                    "apiParameterId": 9230,
                    "apiParameterRequired": true,
                    "apiParameterName": "endpoint-id",
                    "apiParameterLocation": "path",
                    "apiParameterType": "integer",
                    "apiParameterNotes": null,
                    "apiParamLogicId": 32649,
                    "array": false,
                    "apiParameterRestriction": {
                        "rangeRestriction": {
                            "rangeMin": 6,
                            "rangeMax": 15
                        }
                    }
                },
                {
                    "apiParameterId": 8793,
                    "apiParameterRequired": true,
                    "apiParameterName": "resourceId",
                    "apiParameterLocation": "path",
                    "apiParameterType": "string",
                    "apiParameterNotes": null,
                    "apiParamLogicId": 32650,
                    "array": false,
                    "apiParameterRestriction": null
                }
            ]
        }
    ]
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

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

  6. Pick the appropriate resource from the returned array and store its apiResourceId value.

  7. Run the Get a Resource operation for the complete representation of the object.

  8. Modify the returned object.

  9. PUT the object back to the same URL as the GET: /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources/{apiResourceId}.

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

Remove a Resource

This operation removes a resource from an endpoint version. You can only remove resources associated with versions that have never been activated on the staging or production network.

DELETE /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources/{apiResourceId}

Sample: /api-definitions/v2/endpoints/12892/versions/1/resources/7689

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 12892 The unique identifier for the endpoint.
versionNumber Integer 1 The endpoint version number.
apiResourceId Integer 7689 The unique identifier for the 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 returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

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

  6. Pick the appropriate resource from the returned array and store its apiResourceId value.

  7. Make a DELETE request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/resources/{apiResourceId}.

A 204 response confirms the resource has been deleted.

Get Cache Settings

This operation returns the caching settings configured for an endpoint version and its associated resources.

GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cache

Sample: /api-definitions/v2/endpoints/288595/versions/23/settings/cache

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 288595 The unique identifier for the endpoint.
versionNumber Integer 23 The unique identifier for the endpoint version.

Status 200 application/json

Response Body:

{
    "enabled": true,
    "option": "CACHE",
    "maxAge": {
        "duration": 123,
        "unit": "SECONDS"
    },
    "serveStale": false,
    "downstreamCaching": {
        "option": "NOT_ALLOW_CACHING",
        "lifetime": "SMALLER_VALUE",
        "maxAge": null,
        "headers": "CACHE_CONTROL_AND_EXPIRES",
        "markAsPrivate": false
    },
    "errorCaching": {
        "enabled": false,
        "maxAge": null,
        "preserveStale": false
    },
    "resources": {
        "12083": {
            "path": "/1",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "PUT"
            ],
            "option": "CACHE",
            "maxAge": {
                "duration": 123,
                "unit": "SECONDS"
            },
            "serveStale": false,
            "inheritsFromEndpoint": true
        },
        "12084": {
            "path": "/2",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "OPTIONS",
                "PUT",
                "PATCH"
            ],
            "option": "BYPASS_CACHE",
            "maxAge": null,
            "serveStale": false,
            "inheritsFromEndpoint": false
        }
    }
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Make a GET request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cache.

The response is a CacheSettings object that displays caching settings for the requested endpoint version and its associated resources.

Update Cache Settings

This operation updates the caching settings configured for an endpoint version and its associated resources.

PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cache

Sample: /api-definitions/v2/endpoints/288595/versions/23/settings/cache

Content-Type: application/json

Request Body:

{
    "enabled": true,
    "option": "CACHE",
    "maxAge": {
        "duration": 123,
        "unit": "SECONDS"
    },
    "serveStale": false,
    "downstreamCaching": {
        "option": "NOT_ALLOW_CACHING",
        "lifetime": "SMALLER_VALUE",
        "maxAge": null,
        "headers": "CACHE_CONTROL_AND_EXPIRES",
        "markAsPrivate": false
    },
    "errorCaching": {
        "enabled": false,
        "maxAge": null,
        "preserveStale": false
    },
    "resources": {
        "12083": {
            "path": "/1",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "PUT"
            ],
            "option": "CACHE",
            "maxAge": {
                "duration": 123,
                "unit": "SECONDS"
            },
            "serveStale": false,
            "inheritsFromEndpoint": true
        },
        "12084": {
            "path": "/2",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "OPTIONS",
                "PUT",
                "PATCH"
            ],
            "option": "BYPASS_CACHE",
            "maxAge": null,
            "serveStale": false,
            "inheritsFromEndpoint": false
        }
    }
}
Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 288595 The unique identifier for the endpoint.
versionNumber Integer 23 The unique identifier for the endpoint version.

Status 200 application/json

Response Body:

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

If you don’t already have apiEndpointId and versionNumber values:

  1. Run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. Run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

To modify endpoint-level cache settings:

  1. Run the Get Cache Settings operation for the complete representation of the object.

  2. Modify the returned object.

  3. PUT the object back to the same URL as the GET: /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cache.

To modify or add cache settings for individual resources:

  1. Run the List Resources operation.

  2. Pick the appropriate resource from the returned array and store its apiResourceId value.

  3. If the apiResourceId is present in the CacheSettings object’s resources, modify the CacheSettings.resources.{apiResourceId} value.

  4. If the apiResourceId is absent from the CacheSettings object’s resources, create a new CacheSettings.resources.{apiResourceId} object under that key.

  5. PUT the full object back to the same URL as the GET: /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cache.

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

Get GZIP Settings

This operation returns the GZIP compression settings configured for an endpoint version.

GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/gzip

Sample: /api-definitions/v2/endpoints/288595/versions/23/settings/gzip

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 288595 The unique identifier for the endpoint.
versionNumber Integer 23 The unique identifier for the endpoint version.

Status 200 application/json

Response Body:

{
    "compressResponse": "ALWAYS"
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Make a GET request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/gzip.

The response is a GzipSettings object that displays GZIP compression settings for the requested endpoint version.

Update GZIP Settings

This operation updates the GZIP compression settings configured for an endpoint version.

PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/gzip

Sample: /api-definitions/v2/endpoints/288595/versions/23/settings/gzip

Content-Type: application/json

Request Body:

{
    "compressResponse": "ALWAYS"
}
Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 288595 The unique identifier for the endpoint.
versionNumber Integer 23 The unique identifier for the endpoint version.

Status 200 application/json

Response Body:

{
    "compressResponse": "ALWAYS"
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Run the Get GZIP Settings operation for the complete representation of the object.

  6. Modify the returned object.

  7. PUT the object back to the same URL as the GET: /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/gzip.

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

Get CORS Settings

This operation returns the cross-origin resource sharing (CORS) settings configured for an endpoint version.

GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cors

Sample: /api-definitions/v2/endpoints/288595/versions/23/settings/cors

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 288595 The unique identifier for the endpoint.
versionNumber Integer 23 The unique identifier for the endpoint version.

Status 200 application/json

Response Body:

{
    "enabled": true,
    "allowedOrigins": [
        "*"
    ],
    "allowedHeaders": [
        "Akamai-Cors-Allowed"
    ],
    "allowedMethods": [
        "GET"
    ],
    "allowCredentials": false,
    "exposedHeaders": [
        "Akamai-Cors-Exposed"
    ],
    "preflightMaxAge": 86400
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Make a GET request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cors.

The response is a CorsSettings object that displays CORS settings for the requested endpoint version.

Update CORS Settings

This operation updates the cross-origin resource sharing (CORS) settings configured for an endpoint version.

PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cors

Sample: /api-definitions/v2/endpoints/288595/versions/23/settings/cors

Content-Type: application/json

Request Body:

{
    "enabled": true,
    "allowedOrigins": [
        "*"
    ],
    "allowedHeaders": [
        "Akamai-Cors-Allowed"
    ],
    "allowedMethods": [
        "GET"
    ],
    "allowCredentials": false,
    "exposedHeaders": [
        "Akamai-Cors-Exposed"
    ],
    "preflightMaxAge": 86400
}
Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 288595 The unique identifier for the endpoint.
versionNumber Integer 23 The unique identifier for the endpoint version.

Status 200 application/json

Response Body:

{
    "enabled": true,
    "allowedOrigins": [
        "*"
    ],
    "allowedHeaders": [
        "Akamai-Cors-Allowed"
    ],
    "allowedMethods": [
        "GET"
    ],
    "allowCredentials": false,
    "exposedHeaders": [
        "Akamai-Cors-Exposed"
    ],
    "preflightMaxAge": 86400
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Run the Get CORS Settings operation for the complete representation of the object.

  6. Modify the returned object.

  7. PUT the object back to the same URL as the GET: /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/cors.

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

Get JWT Settings

This operation returns JWT validation settings configured for an endpoint version and its associated resources.

GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/jwt

Sample: /api-definitions/v2/endpoints/288595/versions/23/settings/jwt

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 288595 The unique identifier for the endpoint.
versionNumber Integer 23 The unique identifier for the endpoint version.

Status 200 application/json

Response Body:

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

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Make a GET request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/jwt.

The response is a JwtSettings object that displays JWT validation settings for the requested endpoint version and its associated resources.

Update JWT Settings

This operation updates JWT validation settings configured for an endpoint version and its associated resources.

PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/jwt

Sample: /api-definitions/v2/endpoints/288595/versions/23/settings/jwt

Content-Type: application/json

Request Body:

{
    "enabled": true,
    "settings": {
        "location": "COOKIE",
        "paramName": "cookieWT",
        "clockSkew": 0,
        "validation": {
            "claims": [
                {
                    "name": "aud",
                    "validate": true,
                    "required": false,
                    "value": [
                        "ala"
                    ],
                    "type": "ARRAY"
                },
                {
                    "name": "iss",
                    "validate": true,
                    "required": true,
                    "value": "kot",
                    "type": "STRING"
                },
                {
                    "name": "sub",
                    "validate": true,
                    "required": false,
                    "value": "kozak",
                    "type": "STRING"
                },
                {
                    "name": "exp",
                    "validate": false,
                    "required": false,
                    "value": null,
                    "type": "TIMESTAMP"
                },
                {
                    "name": "nbf",
                    "validate": false,
                    "required": false,
                    "value": null,
                    "type": "TIMESTAMP"
                }
            ],
            "rsaPublicKeyA": {
                "name": "id_rsa-2.pub",
                "content": "-----BEGIN PUBLIC KEY-----\nMIIBIjwE9GQg+OR0WYHtq4AKsvK2eucDs06ejWRDb+uDN\n80jxZCxfweelZKvYT9Qdms/1SJv\nrQIDAQAB\n-----END PUBLIC KEY-----\n"
            },
            "rsaPublicKeyB": null
        }
    },
    "resources": {
        "11904": {
            "enabled": true,
            "path": "/endpoint1",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "OPTIONS",
                "PUT",
                "PATCH"
            ],
            "notes": null,
            "inheritsFromEndpoint": true
        },
        "11903": {
            "enabled": false,
            "path": "/endpoint2",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "OPTIONS",
                "PUT",
                "PATCH"
            ],
            "notes": null,
            "inheritsFromEndpoint": false
        }
    }
}
Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 288595 The unique identifier for the endpoint.
versionNumber Integer 23 The unique identifier for the endpoint version.

Status 200 application/json

Response Body:

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

If you don’t already have apiEndpointId and versionNumber values:

  1. Run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. Run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

To modify endpoint-level JWT validation settings:

  1. Run the Get JWT Settings operation for the complete representation of the object.

  2. Modify the returned object.

  3. PUT the object back to the same URL as the GET: /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/jwt.

To modify JWT validation settings for individual resources:

  1. Run the List Resources operation.

  2. Pick the appropriate resource from the returned array and store its apiResourceId value.

  3. If the apiResourceId is present in the JwtSettings object’s resources, modify the JwtSettings.resources.{apiResourceId} value.

  4. If the apiResourceId is absent from the JwtSettings object’s resources, create a new JwtSettings.resources.{apiResourceId} object under that key.

  5. PUT the full object back to the same URL as the GET: /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/jwt.

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

Get API Privacy Settings

This operation returns the API privacy settings configured for an endpoint version and its associated resources.

GET /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/api-privacy

Sample: /api-definitions/v2/endpoints/288595/versions/23/settings/api-privacy

Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 288595 The unique identifier for the endpoint.
versionNumber Integer 23 The unique identifier for the endpoint version.

Status 200 application/json

Response Body:

{
    "resources": {
        "6362": {
            "path": "/add",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "OPTIONS",
                "PUT",
                "PATCH"
            ],
            "notes": "Public resource with all methods",
            "public": true,
            "inheritsFromEndpoint": true
        }
    },
    "public": true
}
  1. If you don’t already have an apiEndpointId value, run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. If you don’t already have a versionNumber value, run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

  5. Make a GET request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/api-privacy.

The response is an ApiPrivacySettings object that displays API privacy settings for the requested endpoint version and its associated resources.

Update API Privacy Settings

This operation updates the API privacy settings configured for an endpoint version and its associated resources.

PUT /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/api-privacy

Sample: /api-definitions/v2/endpoints/288595/versions/23/settings/api-privacy

Content-Type: application/json

Request Body:

{
    "resources": {
        "6362": {
            "path": "/add",
            "methods": [
                "HEAD",
                "DELETE",
                "POST",
                "GET",
                "OPTIONS",
                "PUT",
                "PATCH"
            ],
            "notes": "Public resource with all methods",
            "public": true,
            "inheritsFromEndpoint": true
        }
    },
    "public": true
}
Parameter Type Sample Description
URL Parameters
apiEndPointId Integer 288595 The unique identifier for the endpoint.
versionNumber Integer 23 The unique identifier for the endpoint version.

Status 200 application/json

Response Body:

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

If you don’t already have apiEndpointId and versionNumber values:

  1. Run the List Endpoints operation.

  2. Pick the appropriate endpoint from the returned array and store its apiEndpointId value.

  3. Run the List Versions operation.

  4. Pick the appropriate endpoint version from the returned array and store its versionNumber value.

To modify endpoint-level API privacy settings:

  1. Run the Get API Privacy Settings operation for the complete representation of the object.

  2. Modify the returned object.

  3. PUT the object back to the same URL as the GET: /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/api-privacy.

To modify API privacy settings for individual resources:

  1. Run the List Resources operation.

  2. Pick the appropriate resource from the returned array and store its apiResourceId value.

  3. If the apiResourceId is present in the ApiPrivacySettings object’s resources, modify the ApiPrivacySettings.resources.{apiResourceId} value.

  4. If the apiResourceId is absent from the ApiPrivacySettings object’s resources, create a new ApiPrivacySettings.resources.{apiResourceId} object under that key.

  5. PUT the full object back to the same URL as the GET: /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/settings/api-privacy.

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

List Categories

This operation lists all categories available to tag endpoints and optionally indicates the number of endpoints tagged under each category.

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

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

Parameter Type Sample Description
Optional Query Parameters
withUsageInfo Boolean true Whether the response should include the usageCount data indicating the number of endpoints under a category, false by default.

Status 200 application/json

Response Body:

[
    {
        "apiCategoryId": 13,
        "apiCategoryName": "Media Delivery",
        "apiCategoryDescription": "web media delivery apis",
        "link": "/api-definitions/v2/categories/13",
        "lockVersion": 139793907,
        "createdBy": "rdslj@akamai.com",
        "createDate": "2013-10-07T17:41:52+0000",
        "updatedBy": "rajdj@akamai.com",
        "updateDate": "2013-10-07T17:41:52+0000",
        "usageCount": 0
    },
    {
        "apiCategoryId": 14,
        "apiCategoryName": "Site Delivery",
        "apiCategoryDescription": "Site delivery apis",
        "link": "/api-definitions/v2/categories/14",
        "lockVersion": 139793908,
        "createdBy": "rdslj@akamai.com",
        "createDate": "2013-10-07T17:41:52+0000",
        "updatedBy": "rajdj@akamai.com",
        "updateDate": "2013-10-07T17:41:52+0000",
        "usageCount": 1
    },
    {
        "apiCategoryName": "__UNCATEGORIZED__",
        "usageCount": 4
    }
]
  1. Optionally set the withUsageInfo query parameter to true if you want the listed categories to show the number of endpoints they apply to.

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

The response is an array of Category objects.

Create a Category

This operation creates a category that you can use to tag endpoints. The request’s apiCategoryName needs to be unique per account.

POST /api-definitions/v2/categories

Content-Type: application/json

Request Body:

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

Status 201 application/json

Headers:

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

Response Body:

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

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

The response reflects back the complete Category object, from which you can store the apiCategoryId value. You can access the newly created category at the URL specified in the Location response header.

Get a Category

This operation returns a specific category that you can use to tag endpoints.

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

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

Parameter Type Sample Description
URL Parameters
apiCategoryId Integer 13 The unique identifier for the category.

Status 200 application/json

Response Body:

{
    "apiCategoryId": 13,
    "apiCategoryName": "Media Delivery",
    "apiCategoryDescription": "web media delivery apis",
    "link": "/api-definitions/v2/categories/13",
    "lockVersion": 139793907,
    "createdBy": "rdslj@akamai.com",
    "createDate": "2013-10-07T17:41:52+0000",
    "updatedBy": "rajdj@akamai.com",
    "updateDate": "2013-10-07T17:41:52+0000"
}
  1. If you don’t already have an apiCategoryId value, run the List Categories operation.

  2. Pick the appropriate category from the returned array and store its apiCategoryId value.

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

The response is a Category object.

Modify a Category

This operation updates a category’s description or unique name.

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

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

Content-Type: application/json

Request Body:

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

Status 200 application/json

Response Body:

{
    "apiCategoryId": 13,
    "apiCategoryName": "Media Delivery",
    "apiCategoryDescription": "web media delivery apis",
    "link": "/api-definitions/v2/categories/13",
    "lockVersion": 139793907,
    "createdBy": "rdslj@akamai.com",
    "createDate": "2013-10-07T17:41:52+0000",
    "updatedBy": "rajdj@akamai.com",
    "updateDate": "2013-10-07T17:41:52+0000"
}
  1. If you don’t already have an apiCategoryId value, run the List Categories operation.

  2. Pick the appropriate category from the returned array and store its apiCategoryId value.

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

  4. Modify the returned object.

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

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

Remove a Category

This operation removes an unassigned category. If you assigned the category to at least one endpoint, the operation returns a 403 error.

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

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

Parameter Type Sample Description
URL Parameters
apiCategoryId Integer 13 The unique identifier for the category.

Status 204

  1. If you don’t already have an apiCategoryId value of the appropriate Category object, run the List Categories operation.

  2. Pick the appropriate category from the returned array and store its apiCategoryId value.

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

A 204 response confirms the category has been deleted.

List Contracts and Groups

You provision each API endpoint within the context of your contract with Akamai and a Luna portal group. This operation lists AcgPair objects. These objects 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/v2/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

This operation lists all hostnames through which API consumers can access an endpoint service under a given contract and group pairing. You can use Property Manager (or PAPI) to create new hostnames to make available to users.

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

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

Parameter Type Sample Description
URL Parameters
contractId String 3-1Cgoa The unique identifier for the contract.
groupId Integer 67890 The unique identifier for the 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/v2/contracts/{contractId}/groups/{groupId}/hosts.

The response features a simple array of available hostname strings.


Last modified: 5/10/2018