loading

API Endpoint Definition API v2

Wrap Kona Site Defender, Bot Manager Premier, and API Gateway features around an API endpoint.

Learn more:


Overview

The API Endpoint Definition API lets you programmatically register a new API endpoint, update the definition of an existing API endpoint, and configure additional API Gateway delivery features for an endpoint.

Who should use this API

Akamai provides APIs for developers, DevOps, and operations personnel as an alternative to using the Luna Control Center’s user interface. You may want to automate and instrument the Akamai Kona Site Defender (KSD) and Web Performance products you are using with APIs. The API provides the same functions available under the Manage API Definitions menu selection of the Luna Control Center.

Note that the use of the term endpoint in this documentation refers to an API service. For all other APIs listed on the Akamai Documentation 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.

You can use this API for many useful tasks, most commonly, to automate deployment or configuration of APIs onto the Akamai platform. You can register your API endpoints by specifying their hostnames and base paths, identify the set of expected URL resources and operations, and, if you’re a KSD customer, configure security constraints related to the size and shape of the exchanged data objects.

This API also introduces additional API Gateway delivery features that can help you manage your APIs more efficiently, improve interoperability, gain control over API access, and enhance the overall performance of your API traffic. These features include API privacy, JSON web tokens (JWT), Cross-origin resource sharing (CORS), caching, and GZIP compression. They are available to you if you add API Gateway to your product.

The API privacy feature lets you control access to endpoints and individual resources. To apply API privacy, you need to deploy API keys. Private endpoints and resources that you register in API Gateway require API consumers to identify with appropriate API keys before they can access these endpoints and resources. For more details on API keys and how you can manage them, see the Key and Quota Management API.

When you register your API endpoints, you specify obligatory hostnames for publishing your APIs over the Akamai network. If you haven’t created any hostnames in Property Manager yet, you can leverage the Property Manager API to batch-create hostnames dynamically and activate API traffic for these hostnames. Once you activate the hostnames, you can deploy your APIs and configure how they respond to requests.

Note that this API does not modify any KSD firewall policies that protect your API endpoints, but is a prerequisite to apply such security. You may use this API to define your API endpoint in order to configure protections for them. Use this API before your security team applies a Kona Site Defender firewall policy to your API endpoints.

Getting started

Before using this API for the first time:

  • Review Get Started on tools that Akamai provides.

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

  • For the delivery features to be available, add the API Gateway behavior to the property configured for your Web Performance Solutions or KSD product and enable the API Gateway feature. For details, see Add API Gateway to your product.

  • Ensure that you have the correct user roles assigned to your account in Luna: WAF Config or WAF Admin for endpoints, resources, versions, and security features management; API Gateway Administrator for API Gateway delivery features; Bot Manager Config or Bot Manager Feature for resource purpose settings.

Reporting

Once you deliver your APIs over the Akamai network and enable various delivery features for your configuration, you can track and analyze data related to your API traffic. The Reporting API provides a set of reports specifically for API Gateway and allows you to retrieve data in a range of intervals. The currently available API Gateway reports can help you learn about the usage of your endpoints, including details such as returned HTTP response codes, methods called on the endpoints, API keys used for request senders’ identification, and JWT denial reasons.

Versioning

This most recent API v2 supersedes API Endpoints API v1. Akamai will continue to support v1 indefinitely, but strongly recommends migration to this new version. It provides version management for APIs configured with Akamai features, and it allows you to use the new Akamai API Gateway features, such as API privacy, JWT validation, CORS, caching, and GZIP compression.

Concurrency control

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

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 API Gateway settings, you can also configure API privacy, JWT validation, CORS, caching, and GZIP compression.

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 Documentation 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,show,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}
Hide an endpoint POST /api-definitions/v2/endpoints/{apiEndPointId}/hide
Show an endpoint POST /api-definitions/v2/endpoints/{apiEndPointId}/show
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}
Hide a version POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/hide
Show a version POST /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/show
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,show,contractId,groupId}

Sample: /api-definitions/v2/endpoints?page=5&pageSize=50&category=Site%20Delivery&contains=cloud%20security&sortBy=updateDate&sortOrder=asc&versionPreference=ACTIVATED_FIRST&show=ONLY_VISIBLE&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.
show Enumeration ONLY_VISIBLE The type of endpoints to return based on their visibility status. By default the API returns ALL endpoints. You can instead decide to return ONLY_VISIBLE endpoints, or ONLY_HIDDEN endpoints.
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,
            "versionHidden": true,
            "clonedFromVersion": null,
            "apiEndPointLocked": false,
            "endpointHidden": true,
            "availableActions": [
                "CLONE",
                "SHOW_ENDPOINT",
                "COMPARE_ENDPOINT",
                "ACTIVATE_ON_STAGING",
                "ACTIVATE_ON_PRODUCTION"
            ],
            "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,
    "versionHidden": true,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "HIDE_ENDPOINT",
        "COMPARE_ENDPOINT",
        "DEACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION"
    ],
    "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,
    "versionHidden": true,
    "apiEndPointLocked": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "HIDE_ENDPOINT",
        "COMPARE_ENDPOINT",
        "ACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION"
    ],
    "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,
    "versionHidden": true,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "protectedByApiKey": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "DEACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION",
        "COMPARE_ENDPOINT",
        "HIDE_ENDPOINT"
    ],
    "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 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.

Hide an endpoint

This operation hides an endpoint and all its versions. You can only hide an endpoint if none of its versions is active on the staging or production network. You cannot activate or delete versions of a hidden endpoint.

POST /api-definitions/v2/endpoints/{apiEndPointId}/hide

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

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

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,
    "versionHidden": true,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "protectedByApiKey": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "DEACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION",
        "COMPARE_ENDPOINT",
        "HIDE_ENDPOINT"
    ],
    "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. Make a POST request to /api-definitions/v2/endpoints/{apiEndPointId}/hide.

The response reflects back the hidden Endpoint object.

Show an endpoint

This operation reveals a hidden endpoint and all its versions.

POST /api-definitions/v2/endpoints/{apiEndPointId}/show

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

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

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,
    "versionHidden": true,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "protectedByApiKey": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "DEACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION",
        "COMPARE_ENDPOINT",
        "HIDE_ENDPOINT"
    ],
    "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. Make a POST request to /api-definitions/v2/endpoints/{apiEndPointId}/show.

The response reflects back the revealed Endpoint object.

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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "SHOW_VERSION"
            ],
            "hidden": true,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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,
    "versionHidden": true,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "HIDE_ENDPOINT",
        "COMPARE_ENDPOINT",
        "DEACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION"
    ],
    "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 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 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.

Hide a version

This operation hides an endpoint version. You can only hide inactive or deactivated versions. You cannot activate or delete hidden versions.

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

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

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,
    "versionHidden": true,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "protectedByApiKey": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "DEACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION",
        "COMPARE_ENDPOINT",
        "HIDE_ENDPOINT"
    ],
    "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 POST request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/hide.

The response reflects back an Endpoint object with the hidden version indicated in the versionNumber field.

Show a version

This operation reveals a hidden endpoint version.

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

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

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,
    "versionHidden": true,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "protectedByApiKey": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "DEACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION",
        "COMPARE_ENDPOINT",
        "HIDE_ENDPOINT"
    ],
    "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 POST request to /api-definitions/v2/endpoints/{apiEndPointId}/versions/{versionNumber}/show.

The response reflects back an Endpoint object with the revealed version indicated in the versionNumber field.

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,
    "versionHidden": true,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "protectedByApiKey": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "DEACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION",
        "COMPARE_ENDPOINT",
        "HIDE_ENDPOINT"
    ],
    "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,
    "versionHidden": true,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "protectedByApiKey": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "DEACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION",
        "COMPARE_ENDPOINT",
        "HIDE_ENDPOINT"
    ],
    "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,
    "versionHidden": true,
    "apiEndPointLocked": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "HIDE_ENDPOINT",
        "COMPARE_ENDPOINT",
        "ACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION"
    ],
    "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
    },
    "cacheKey": {
        "customize": true,
        "option": "INCLUDE_ALL_PRESERVE_ORDER"
    },
    "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,
            "cacheKey": {
                "customize": true,
                "option": "INCLUDE",
                "parameters": [
                    "includeMe"
                ],
                "exactMatch": 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/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
    },
    "cacheKey": {
        "customize": true,
        "option": "INCLUDE_ALL_PRESERVE_ORDER"
    },
    "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,
            "cacheKey": {
                "customize": true,
                "option": "INCLUDE",
                "parameters": [
                    "includeMe"
                ],
                "exactMatch": 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:

{
    "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
    },
    "cacheKey": {
        "customize": true,
        "option": "INCLUDE_ALL_PRESERVE_ORDER"
    },
    "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,
            "cacheKey": {
                "customize": true,
                "option": "INCLUDE",
                "parameters": [
                    "includeMe"
                ],
                "exactMatch": 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 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.

Data

This section provides details for each type of data object the API exchanges.

Whenever [] appears at the end of an object’s name, it indicates that the object represents any element in an array of objects.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required to be present, regardless of whether its value is empty or null.
Member is optional, and may be omitted in some cases.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it’s either ignored, or causes an error.

EndpointList

Encapsulates information about a collection of requested endpoints.

Download schema: apiEndpointListDto-schema.json

EndpointList members

Member Type Required Description
apiEndPoints Endpoint Array The collection of returned Endpoint objects.
page Integer The number of the current page with results.
pageSize Integer The number of endpoints on each page with results.
totalSize Integer The total number of endpoints available in the returned set.

Endpoint

Encapsulates information about an endpoint and its associated resources.

Download schema: apiEndpointCloneDto-schema.json, apiEndpointWithResourceDto-schema.json

Sample GET:

{
    "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,
    "versionHidden": true,
    "clonedFromVersion": null,
    "apiEndPointLocked": false,
    "endpointHidden": true,
    "availableActions": [
        "CLONE",
        "HIDE_ENDPOINT",
        "COMPARE_ENDPOINT",
        "DEACTIVATE_ON_STAGING",
        "ACTIVATE_ON_PRODUCTION"
    ],
    "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
}

Endpoint members

Member Type Clone Create/Modify Description
akamaiSecurityRestrictions Endpoint.akamaiSecurityRestrictions, Null Encapsulates information about the Kona Site Defender security restrictions that you apply to an API. Note that you should only include these details in your requests if you’re a Kona Site Defender customer.
apiCategoryIds Array, Null The Category identifiers that apply to the endpoint. The value is null for uncategorized endpoints.
apiEndPointHosts Array The hostnames that may receive traffic for the endpoint. At least one hostname is required before activating the endpoint.
apiEndPointId Integer Read-only. The unique identifier for the endpoint. For the clone operation, this is the ID of the source endpoint.
apiEndPointLocked Boolean, Null Read-only. Whether the endpoint version is read-only.
apiEndPointName String The name of the endpoint.
apiEndPointScheme Enumeration, Null The URL scheme to which the endpoint may respond, either http, https, or http/https for both.
apiResources Resource Array The resources associated with the endpoint.
availableActions Array, Null Read-only. The collection of available actions that you can perform on the endpoint depending on its versions’ activation status. For possible values, see Endpoint.availableActions Values.
basePath String The URL path that serves as a root prefix for all resources’ resourcePath values for the endpoint. This is / if empty. Do not append a / character to the path.
clonedFromVersion Integer, Null Read-only. For cloned endpoints, the unique identifier for the source endpoint version.
consumeType Enumeration, Null The content type the endpoint exchanges, either json, xml, json/xml for dual-format APIs, any, or none.
contractId String Read-only. The unique identifier for the contract with Akamai under which you provisioned security and delivery settings for this API.
createDate String, Null Read-only. The ISO–6801 timestamp indicating when you created the endpoint.
createdBy String, Null Read-only. The identifier for the user who created the endpoint.
description String The description of the endpoint.
endpointHidden Boolean, Null Read-only. Whether the endpoint is hidden. You cannot activate or delete versions of a hidden endpoint. If you want to do so, you first need to reveal the endpoint by running the Show an endpoint operation.
groupId Integer Read-only. The unique identifier for the group in the Luna portal under which you provisioned security and delivery settings for this API.
lockVersion Integer Read-only. The identifier for the last modification of an endpoint version, used for optimistic locking. See Concurrency Control for details.
productionStatus Enumeration, Null Read-only. The version activation status on the production network, either PENDING if the version contains changes that are being propagated to the network, ACTIVE if the version is active, DEACTIVATED if the version had been active once but has been deactivated, or FAILED if an activation or deactivation attempt for this version has failed. The value is null for versions that have never been activated on this network.
productionVersion Endpoint.productionVersion, Null Read-only. Encapsulates information about an endpoint version’s activation status on the production network.
protectedByApiKey Boolean Read-only. Whether you enabled API key protection for the endpoint version by making the version private.
securityScheme Endpoint.securityScheme, Null Encapsulates information about the key with which users may access the endpoint.
stagingStatus Enumeration, Null Read-only. The version activation status on the staging network, either PENDING if the version contains changes that are being propagated to the network, ACTIVE if the version is active, DEACTIVATED if the version had been active once but has been deactivated, or FAILED if an activation or deactivation attempt for this version has failed. The value is null for versions that have never been activated on this network.
stagingVersion Endpoint.stagingVersion, Null Read-only. Encapsulates information about an endpoint version’s activation status on the staging network.
updateDate String, Null Read-only. The ISO–6801 timestamp indicating when you last modified the endpoint.
updatedBy String, Null Read-only. The identifier for the user who last modified the endpoint.
versionHidden Boolean, Null Read-only. Whether the endpoint version is hidden. You cannot activate or delete hidden versions. If you want to do so, you first need to reveal the version by running the Show a version operation.
versionNumber Integer The endpoint version number. For the clone operation, this is the source endpoint version number.
Endpoint.akamaiSecurityRestrictions: Encapsulates information about the Kona Site Defender security restrictions that you apply to an API. Note that you should only include these details in your requests if you’re a Kona Site Defender customer.
MAX_BODY_SIZE Integer, Null The maximum allowed size of a request body.
MAX_DOC_DEPTH Integer, Null The maximum depth of nested data elements allowed in a request body.
MAX_ELEMENT_NAME_LENGTH Integer, Null The maximum length of an XML element name or JSON object key name allowed in a request body.
MAX_INTEGER_VALUE Integer, Null The maximum integer value allowed in a request body.
MAX_JSONXML_ELEMENT Integer, Null The maximum number of XML elements, JSON object keys, or array items allowed in a request body.
MAX_STRING_LENGTH Integer, Null The maximum length of any string value in a request body.
POSITIVE_SECURITY_ENABLED Enumeration Whether the API request body and resource constraints should be enforced as whitelists in your KSD security policies. Either 1 for enabled security constraints, or 0 for disabled.
Endpoint.productionVersion: Encapsulates information about an endpoint version’s activation status on the production network.
status Enumeration, Null The activation status on the production network, either PENDING if the version contains changes that are being propagated to the network, ACTIVE if the version is active, DEACTIVATED if the version had been active once but has been deactivated, or FAILED if an activation or deactivation attempt for this version has failed. The value is null for versions that have never been activated on this network.
versionNumber Integer The endpoint version number.
Endpoint.securityScheme: Encapsulates information about the key with which users may access the endpoint.
securitySchemeDetail Endpoint.securityScheme.securitySchemeDetail Encapsulates information about the location of the API key.
securitySchemeType Enumeration The type of security scheme implemented for the endpoint. The only valid value is apikey.
Endpoint.securityScheme.securitySchemeDetail: Encapsulates information about the location of the API key.
apiKeyLocation Enumeration The location of the API key in incoming requests, either cookie, header, or query parameter.
apiKeyName String The name of the header, query parameter, or cookie where you located the API key.
Endpoint.stagingVersion: Encapsulates information about an endpoint version’s activation status on the staging network.
status Enumeration, Null The activation status on the staging network, either PENDING if the version contains changes that are being propagated to the network, ACTIVE if the version is active, DEACTIVATED if the version had been active once but has been deactivated, or FAILED if an activation or deactivation attempt for this version has failed. The value is null for versions that have never been activated on this network.
versionNumber Integer The endpoint version number.

Endpoint.availableActions Values

The following values indicate the set of availableActions you can perform on an endpoint depending on its activation status:

Value Description
ACTIVATE_ON_PRODUCTION You can activate at least one version of the endpoint on the production network.
ACTIVATE_ON_STAGING You can activate at least one version of the endpoint on the staging network.
CLONE_ENDPOINT You can clone the endpoint.
DEACTIVATE_ON_PRODUCTION You can deactivate at least one version of the endpoint on the production network.
DEACTIVATE_ON_STAGING You can deactivate at least one version of the endpoint on the staging network.
DELETE You can delete the endpoint.
EDIT_ENDPOINT_DEFINITION You can edit the endpoint and resource settings of at least one version of the endpoint.
HIDE_ENDPOINT You can hide the endpoint and all its versions.
SHOW_ENDPOINT You can reveal the endpoint and all its versions.

VersionList

Encapsulates information about all versions of an endpoint.

Download schema: apiEndpointVersionListDto-schema.json

Sample GET:

{
    "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "SHOW_VERSION"
            ],
            "hidden": true,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "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",
                "HIDE_VERSION"
            ],
            "hidden": false,
            "versionNumber": 13,
            "lockVersion": 0
        }
    ]
}

VersionList members

Member Type Required Description
apiEndPointId Integer The unique identifier for the endpoint.
apiEndPointName String The name of the endpoint.
apiVersions VersionList.apiVersions[] Encapsulates information about each endpoint version within a collection.
VersionList.apiVersions[]: Encapsulates information about each endpoint version within a collection.
apiEndPointVersionId Integer The unique identifier for the endpoint version.
availableActions Array, Null Read-only. The collection of available actions that you can perform on the version depending on the version’s activation status. For possible values, see VersionList.apiVersions[].availableActions Values.
basedOn Integer, Null For cloned versions, the unique identifier for the source version.
basePath String The URL path that serves as a root prefix for all resources’ resourcePath values. This is / if empty. Do not append a / character to the path.
createDate String Read-only. The ISO–6801 timestamp indicating when you created the endpoint version.
createdBy String The identifier for the user who created the version.
description String, Null The description of the endpoint version.
hidden Boolean, Null Read-only. Whether the endpoint version is hidden. You cannot activate or delete hidden versions. If you want to do so, you first need to reveal the version by running the Show a version operation.
isVersionLocked Boolean Whether the endpoint version is read-only.
lockVersion Integer The identifier for the last modification of an endpoint version, used for optimistic locking. See Concurrency Control for details.
productionDate String, Null Read-only. The ISO–6801 timestamp indicating when you activated the endpoint version on the production network.
productionStatus Enumeration, Null Read-only. The version activation status on the production network, either PENDING if the version contains changes that are being propagated to the network, ACTIVE if the version is active, DEACTIVATED if the version had been active once but has been deactivated, or FAILED if an activation or deactivation attempt for this version has failed. The value is null for versions that have never been activated on this network.
stagingDate String, Null Read-only. The ISO–6801 timestamp indicating when you activated the endpoint version on the staging network.
stagingStatus Enumeration, Null Read-only. The version activation status on the staging network, either PENDING if the version contains changes that are being propagated to the network, ACTIVE if the version is active, DEACTIVATED if the version had been active once but has been deactivated, or FAILED if an activation or deactivation attempt for this version has failed. The value is null for versions that have never been activated on this network.
updateDate String Read-only. The ISO–6801 timestamp indicating when you last modified the endpoint version.
updatedBy String The identifier for the user who last modified the version.
versionNumber Integer The endpoint version number.

VersionList.apiVersions[].availableActions Values

The following values indicate the set of availableActions you can perform on an endpoint version depending on its activation status:

Value Description
ACTIVATE_ON_PRODUCTION You can activate the version on the production network.
ACTIVATE_ON_STAGING You can activate the version on the staging network.
CLONE_ENDPOINT You can clone the entire endpoint that includes the version.
CLONE_VERSION You can clone the version.
COMPARE_AAG_SETTINGS You can compare the version’s API privacy, JWT validation, CORS, Caching, and GZIP compression settings with another version.
COMPARE_ENDPOINT You can compare the version’s endpoint definition and resource settings with another version.
COMPARE_RESOURCE_PURPOSES If you’re a Bot Manager customer, you can compare the version’s resource purpose settings with another version.
DEACTIVATE_ON_PRODUCTION You can deactivate the version on the production network.
DEACTIVATE_ON_STAGING You can deactivate the version on the staging network.
DELETE You can delete the version.
EDIT_AAG_SETTINGS You can edit the version’s API privacy, JWT validation, CORS, Caching, and GZIP compression settings.
EDIT_ENDPOINT_DEFINITION You can edit the version’s endpoint definition and resource settings.
HIDE_VERSION You can hide the version.
RESOURCE You can add and edit resources associated with the version.
SHOW_VERSION You can reveal the version.
VIEW_AAG_SETTINGS You can view the version’s API privacy, JWT validation, CORS, Caching, and GZIP compression settings.

Resource

Encapsulates information about a Resource associated with an Endpoint.

Download schema: apiResourceMethParamsDto-schema.json

Sample GET:

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

Resource members

Member Type Required Description
apiResourceClonedFromId Integer, Null Read-only. For cloned resources, the unique identifier for the source resource.
apiResourceId Integer, Null Read-only. The unique identifier for the resource.
apiResourceLogicId Integer, Null Read-only. The unique identifier for the resource across all endpoint versions.
apiResourceMethods Method Array The collection of HTTP methods to which the resource may respond.
apiResourceName String The name of the resource.
createDate String Read-only. The ISO–6801 timestamp indicating when you created the resource.
createdBy String Read-only. The identifier for the user who created the resource.
description String, Null The description to clarify the resource’s function within the API.
link String, Null Read-only. The location of the navigable resource within this API, for use by API clients. See Hypermedia for details.
lockVersion Number Read-only. The identifier used for optimistic locking. See Concurrency Control for details.
private Boolean Read-only. Whether the resource is private. API consumers can access private resources only if they identify with an appropriate API key.
resourcePath String The URL path relative to the hostnames on which the resource resides. When entering a resource path, you can use curly brackets ({}) to define path parameters (for example, /path/{pathparam}). If you decide to do so, ensure that the value of the apiParameterName member in the corresponding parameter definition matches the name that you specified in the resource path.
updateDate String Read-only. The ISO–6801 timestamp indicating when you last modified the resource.
updatedBy String Read-only. The identifier for the user who last modified the resource.

Method

Encapsulates information about an HTTP method to which a resource may respond.

Download schema: apiMethodParametersDto-schema.json

Method members

Member Type Required Description
apiParameters Parameter Array The collection of parameters assigned to the method.
apiResourceMethod Enumeration The core HTTP method to which the resource may respond, either get, put, post, delete, head, patch, or options.
apiResourceMethodId Integer, Null Read-only. The unique identifier for the resource’s allowed method.
apiResourceMethodLogicId Integer, Null Read-only. The unique identifier for the resource’s method across all endpoint versions.

Parameter

Encapsulates information about a method’s parameter.

Download schema: apiParameterDto-schema.json

Parameter members

Member Type Required Description
apiChildParameters Parameter Array The collection of child JSON members or XML elements for JSON or XML body type parameters.
apiParameterId Integer Read-only. The unique identifier for the parameter.
apiParameterLocation Enumeration, Null The parameter location in the request, either header, cookie, query, or body.
apiParameterName String The name of the parameter. If the corresponding apiParameterLocation is path, ensure that this value matches the parameter name you specified in the resourcePath.
apiParameterNotes String, Null The description to clarify the parameter’s function.
apiParameterRequired Boolean Whether the parameter is required. If the corresponding apiParameterLocation is path, set this member to true.
apiParameterRestriction Parameter.apiParameterRestriction, Null Encapsulates information about restrictions and XML representation rules specified for the parameter.
apiParameterType Enumeration The data type of the parameter, either string, integer, number, boolean, or json/xml for JSON or XML objects.
apiParamLogicId Integer Read-only. The unique identifier for the parameter across all endpoint versions.
apiResourceMethParamId Integer, Null Read-only. The unique identifier for the parameter’s parent method.
array Boolean Whether the parameter can express more than one value. This member is only applicable for apiChildParameters that you can specify if the corresponding apiParameterLocation is body and the apiParameterType is json/xml. If you enable this, also define the arrayRestriction member.
Parameter.apiParameterRestriction: Encapsulates information about restrictions and XML representation rules specified for the parameter.
arrayRestriction Parameter.apiParameterRestriction.arrayRestriction, Null Encapsulates information about array restrictions for array type parameters. Define this object only if you enabled the corresponding array member.
lengthRestriction Parameter.apiParameterRestriction.lengthRestriction, Null Encapsulates information about length restrictions for string type parameters.
numberRangeRestriction Parameter.apiParameterRestriction.numberRangeRestriction, Null Encapsulates information about range restrictions for number type parameters.
rangeRestriction Parameter.apiParameterRestriction.rangeRestriction, Null Encapsulates information about range restrictions for integer type parameters.
xmlConversionRule Parameter.apiParameterRestriction.xmlConversionRule Encapsulates information about an XML representation of a JSON-encoded parameter.
Parameter.apiParameterRestriction.arrayRestriction: Encapsulates information about array restrictions for array type parameters. Define this object only if you enabled the corresponding array member.
collectionFormat Enumeration The format of the array that specifies how you separated array values, either the default csv for comma separated values, ssv for space separated values, tsv for tab separated values, pipes for pipe separated values, or multi for multiple parameter instances instead of multiple values for a single instance.
maxItems Integer The maximum allowed number of array items.
minItems Integer The minimum allowed number of array items.
uniqueItems Boolean Whether the array contains only unique items.
Parameter.apiParameterRestriction.lengthRestriction: Encapsulates information about length restrictions for string type parameters.
lengthMax Integer, Null The maximum allowed number of characters in the string.
lengthMin Integer, Null The minimum allowed number of characters in the string.
Parameter.apiParameterRestriction.numberRangeRestriction: Encapsulates information about range restrictions for number type parameters.
numberRangeMax Number, Null The maximum range restriction.
numberRangeMin Number, Null The minimum range restriction.
Parameter.apiParameterRestriction.rangeRestriction: Encapsulates information about range restrictions for integer type parameters.
rangeMax Integer, Null The maximum range restriction.
rangeMin Integer, Null The minimum range restriction.
Parameter.apiParameterRestriction.xmlConversionRule: Encapsulates information about an XML representation of a JSON-encoded parameter.
attribute Boolean Whether the parameter should be represented as an attribute.
name String The name of the parameter in XML. By default, the XML name is the same as the parameter name specified in the API definition.
namespace String The XML namespace.
prefix String The prefix for the XML namespace.
wrapped Boolean Whether the parameter should be wrapped in a parent XML element.

ImportResult

Encapsulates information about a result of an import operation, including endpoint details and a list of potential issues.

Download schema: importResult-schema.json

Sample POST response:

{
    "apiEndpointDetails": {
        "createdBy": null,
        "createDate": null,
        "updateDate": null,
        "updatedBy": null,
        "apiEndPointId": null,
        "apiEndPointName": "Swagger Petstore",
        "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification",
        "basePath": "/api",
        "apiEndPointScheme": "http",
        "consumeType": "json",
        "groupId": null,
        "versionNumber": null,
        "clonedFromVersion": null,
        "apiEndPointLocked": null,
        "stagingVersion": null,
        "productionVersion": null,
        "protectedByApiKey": false,
        "apiProtectVersion": null,
        "apiEndPointHosts": [
            "petstore.swagger.io"
        ],
        "apiCategoryIds": null,
        "contractId": null,
        "securityScheme": null,
        "akamaiSecurityRestrictions": null,
        "stagingStatus": null,
        "productionStatus": null,
        "apiResources": [
            {
                "createdBy": null,
                "createDate": null,
                "updateDate": null,
                "updatedBy": null,
                "apiResourceId": null,
                "apiResourceName": "/pets",
                "resourcePath": "/pets",
                "description": null,
                "link": null,
                "apiResourceClonedFromId": null,
                "apiResourceLogicId": null,
                "private": false,
                "apiResourceMethods": [
                    {
                        "apiResourceMethodId": null,
                        "apiResourceMethod": "POST",
                        "apiParameters": [],
                        "apiResourceMethodLogicId": null
                    }
                ],
                "lockVersion": -1
            }
        ],
        "lockVersion": -1
    },
    "problems": [
        {
            "type": "/api-definitions/error-types/IMPORT-INVALID-SCHEMA",
            "title": "Invalid schema",
            "detail": "object instance has properties which are not allowed by the schema: [\"unrecognizable\"]",
            "pointer": "/paths/~1pets/post",
            "level": "error",
            "domain": "validation",
            "keyword": "additionalProperties"
        }
    ]
}

ImportResult members

Member Type Required Description
apiEndpointDetails Endpoint Encapsulates information about the imported endpoint.
problems ImportResult.problems[] Encapsulates debugging information for error responses.
ImportResult.problems[]: Encapsulates debugging information for error responses.
detail String The detailed error message.
errors ImportResult.problems[] The collection of nested error responses.
instance String The non-referencable URL for the error instance.
status Integer The HTTP status code.
title String The title of the error.
type String The URL for the error type.

Activation

Encapsulates information about an endpoint version activation.

Download schema: activationDto-schema.json

Sample POST request:

{
    "networks": [
        "STAGING",
        "PRODUCTION"
    ],
    "notificationRecipients": [
        "joe@example.com"
    ],
    "notes": "Activating endpoint in both networks."
}

Activation members

Member Type Required Description
networks Array The network environments where you activate the endpoint version, either STAGING or PRODUCTION.
notes String The notes describing the version that you activate.
notificationRecipients Array The email addresses where the system sends the activation notification.

CacheSettings

Encapsulates information about caching settings configured for an endpoint. Caching settings specify properties such as the maximum age of cached content, caching HTTP error responses, downstream cacheability, and cache key customization. You can set specific caching instructions for each resource within an endpoint version. You can configure caching settings if the API Gateway product is in your contract.

Download schema: cacheSettingsDto-schema.json

Sample GET:

{
    "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
    },
    "cacheKey": {
        "customize": true,
        "option": "INCLUDE_ALL_PRESERVE_ORDER"
    },
    "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,
            "cacheKey": {
                "customize": true,
                "option": "INCLUDE",
                "parameters": [
                    "includeMe"
                ],
                "exactMatch": true
            }
        }
    }
}

CacheSettings members

Member Type Required Description
cacheKey CacheSettings.resources.cacheKey Encapsulates information about the cache key settings configured for an endpoint or resource.
downstreamCaching CacheSettings.downstreamCaching Encapsulates information about downstream caching settings. Downstream caching refers to the caching instructions associated with objects sent with responses toward clients—browsers, mobile devices, or client proxies.
enabled Boolean Whether you enabled caching for the endpoint.
errorCaching CacheSettings.errorCaching Encapsulates information about error caching settings.
maxAge CacheSettings.resources.maxAge Encapsulates information about the maximum duration to keep content in a cache.
option Enumeration The options for how to pass cached content, either CACHE to enable caching in Akamai platform servers according to the instructions you specify, BYPASS_CACHE to disallow caching in Akamai platform servers and keep the existing cache entries, NO_STORE to disallow caching in Akamai platform servers and remove the existing cache entries, HONOR_ORIGIN_CACHE_CONTROL to apply caching instructions specified in your origin’s Cache-Control header, HONOR_ORIGIN_EXPIRES to apply caching instructions specified in your origin’s Expires header, or HONOR_ORIGIN_CACHE_CONTROL_AND_EXPIRES to apply caching instructions specified in your origin’s Cache-Control and Expires headers.
resources CacheSettings.resources Encapsulates information about caching settings for each resource associated with an endpoint version. The resources are available through a map of resourceId keys.
serveStale Boolean, Null Whether to serve stale responses when the origin is unreachable and content revalidation is not possible.
CacheSettings.cacheKey: Encapsulates information about the cache key settings configured for an endpoint or resource.
customize Boolean Whether you want to customize cache key settings for an endpoint.
exactMatch Boolean, Null Whether query parameters in incoming requests should match exactly the string items in the corresponding parameters member. If false, even the parameters that just begin with the strings you specified in the parameters member will match. This is only relevant if you set the corresponding option member to either INCLUDE or IGNORE.
option Enumeration, Null The option for cache key customization, either INCLUDE_ALL_PRESERVE_ORDER to include all query parameters as part of a cache key and keep their default order, INCLUDE_ALL_ALPHABETIZE_ORDER to include all query parameters as part of a cache key and sort them alphabetically, IGNORE_ALL to exclude all query parameters from a cache key, INCLUDE to include only specific parameters as part of a cache key, or IGNORE to exclude only specific parameters from a cache key. If you select INCLUDE or IGNORE, also specify the corresponding parameters member.
parameters Array, Null The list of parameters to include in or exclude from cache keys, depending on the option you selected. This is only relevant if you set the corresponding option member to either INCLUDE or IGNORE.
CacheSettings.downstreamCaching: Encapsulates information about downstream caching settings. Downstream caching refers to the caching instructions associated with objects sent with responses toward clients—browsers, mobile devices, or client proxies.
headers Enumeration The policy for sending headers downstream, either CACHE_CONTROL_AND_EXPIRES to send both Cache-Control and Expires headers, CACHE_CONTROL to send only the Cache-Control header, EXPIRES to send only the Expires header, or SAME_AS_ORIGIN to send the same headers as your origin.
lifetime Enumeration The cache lifetime policy, either SMALLER_VALUE for a value smaller than specified in the origin header or the remaining edge TTL, GREATER_VALUE for a value greater than specified in the origin header or the remaining edge TTL, REMAINING_EDGE_TTL for a remaining edge TTL, FULL_EDGE_TTL for a full edge TTL, FIXED_VALUE for a value that you specify, or CALCULATES_EXPIRES_FROM_ORIGIN_CACHE_CONTROL for calculating the maximum age from the origin Cache-Control header.
markAsPrivate Boolean, Null Whether to disallow storing responses in a shared cache. This is useful when you want to set a maximum age for the end client, but have shared caches not store the response.
maxAge CacheSettings.resources.maxAge Encapsulates information about the maximum duration to keep content in a cache.
option Enumeration The option for downstream caching, either ALLOW_CACHING to allow downstream caching, ALLOW_CACHING_REQUIRES_REVALIDATION to allow downstream caching, but require origin revalidation, NOT_ALLOW_CACHING to disallow downstream caching, PASS_CACHEABILITY_HEADERS_FROM_ORIGIN to pass cacheability headers from your origin, or DO_NOT_SEND_HEADERS to disallow sending headers and apply browser defaults.
CacheSettings.downstreamCaching.maxAge: Encapsulates information about the maximum duration to keep content in a cache.
duration Integer The maximum duration of content caching in the selected unit of time.
unit Enumeration The unit of time for content caching, either DAYS, HOURS, MINUTES, or SECONDS.
CacheSettings.errorCaching: Encapsulates information about error caching settings.
enabled Boolean Whether you enabled error caching.
maxAge CacheSettings.resources.maxAge Encapsulates information about the maximum duration to keep content in a cache.
preserveStale Boolean, Null Whether to preserve stale responses when the origin is unreachable and content revalidation is not possible.
CacheSettings.errorCaching.maxAge: Encapsulates information about the maximum duration to keep content in a cache.
duration Integer The maximum duration of content caching in the selected unit of time.
unit Enumeration The unit of time for content caching, either DAYS, HOURS, MINUTES, or SECONDS.
CacheSettings.maxAge: Encapsulates information about the maximum duration to keep content in a cache.
duration Integer The maximum duration of content caching in the selected unit of time.
unit Enumeration The unit of time for content caching, either DAYS, HOURS, MINUTES, or SECONDS.
CacheSettings.resources: Encapsulates information about caching settings for each resource associated with an endpoint version. The resources are available through a map of resourceId keys.
cacheKey CacheSettings.resources.cacheKey Encapsulates information about the cache key settings configured for an endpoint or resource.
inheritsFromEndpoint Boolean Whether the resource inherits the top-level API caching settings.
maxAge CacheSettings.resources.maxAge Encapsulates information about the maximum duration to keep content in a cache.
option Enumeration The resource caching option, either CACHE to enable caching in Akamai platform servers according to the instructions you specify, BYPASS_CACHE to send requests straight to origin and disallow caching in downstream caches, NO_STORE to disallow caching in Akamai platform servers, HONOR_ORIGIN_CACHE_CONTROL to apply caching instructions specified in your origin’s Cache-Control header, HONOR_ORIGIN_EXPIRES to apply caching instructions specified in your origin’s Expires header, or HONOR_ORIGIN_CACHE_CONTROL_AND_EXPIRES to apply caching instructions specified in your origin’s Cache-Control and Expires headers. If set, overwrites the caching instructions set at the endpoint level.
serveStale Boolean Whether to serve stale objects when the origin is unreachable and content revalidation is not possible.
CacheSettings.resources.cacheKey: Encapsulates information about the cache key settings configured for an endpoint or resource.
customize Boolean Whether you want to customize cache key settings for an endpoint.
exactMatch Boolean, Null Whether query parameters in incoming requests should match exactly the string items in the corresponding parameters member. If false, even the parameters that just begin with the strings you specified in the parameters member will match. This is only relevant if you set the corresponding option member to either INCLUDE or IGNORE.
option Enumeration, Null The option for cache key customization, either INCLUDE_ALL_PRESERVE_ORDER to include all query parameters as part of a cache key and keep their default order, INCLUDE_ALL_ALPHABETIZE_ORDER to include all query parameters as part of a cache key and sort them alphabetically, IGNORE_ALL to exclude all query parameters from a cache key, INCLUDE to include only specific parameters as part of a cache key, or IGNORE to exclude only specific parameters from a cache key. If you select INCLUDE or IGNORE, also specify the corresponding parameters member.
parameters Array, Null The list of parameters to include in or exclude from cache keys, depending on the option you selected. This is only relevant if you set the corresponding option member to either INCLUDE or IGNORE.
CacheSettings.resources.maxAge: Encapsulates information about the maximum duration to keep content in a cache.
duration Integer The maximum duration of content caching in the selected unit of time.
unit Enumeration The unit of time for content caching, either DAYS, HOURS, MINUTES, or SECONDS.
CacheSettings.resources.{apiResourceId}: Encapsulates information about caching settings configured for a resource within your API.
enabled Boolean Whether you enabled caching for the resource. If set, overwrites the endpoint-level caching settings.
methods Array Read-only. The methods associated with the resource, either POST, GET, PUT, DELETE, HEAD, OPTIONS, or PATCH.
path String Read-only. The URL path relative to the hostnames on which the resource resides.

ApiPrivacySettings

Encapsulates information about API privacy settings configured for an endpoint and its associated resources. You can configure API privacy settings if the API Gateway product is in your contract.

Download schema: apiPrivacySettingsDto-schema.json

Sample GET:

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

ApiPrivacySettings members

Member Type Required Description
public Boolean Whether the endpoint is public, that is, accessible without an API key.
resources ApiPrivacySettings.resources Encapsulates information about each resource’s privacy settings.
ApiPrivacySettings.resources.{apiResourceId}: Encapsulates information about a resource’s privacy settings.
inheritsFromEndpoint Boolean Read-only. Whether the resource inherits the top-level API privacy settings.
methods Array Read-only. The methods associated with the resource, either POST, GET, PUT, DELETE, HEAD, OPTIONS, or PATCH.
notes String Read-only. The notes describing the purpose of the resource.
path String Read-only. The URL path relative to the hostnames on which the resource resides.
public Boolean Whether the resource is public, that is, accessible without an API key.

GzipSettings

Encapsulates information about GZIP compression settings configured for an endpoint. This feature ensures proper content compression for bandwidth savings. You can configure GZIP compression settings if the API Gateway product is in your contract.

Download schema: gzipDto-schema.json

Sample GET:

{
    "compressResponse": "ALWAYS"
}

GzipSettings members

Member Type Required Description
compressResponse Enumeration The type of GZIP compression configuration that you select, either ALWAYS for compressing all responses without restrictions, NEVER for no GZIP compression, or SAME_AS_ORIGIN for the same compression rules as specified for your origin server via the Content-Encoding header.

CorsSettings

Encapsulates information about cross-origin resource sharing (CORS) settings configured for an endpoint. CORS enables clients to request restricted resources from external domains outside the domain that served the first resource. You can configure CORS settings if the API Gateway product is in your contract.

Download schema: corsDto-schema.json

Sample GET:

{
    "enabled": true,
    "allowedOrigins": [
        "*"
    ],
    "allowedHeaders": [
        "Akamai-Cors-Allowed"
    ],
    "allowedMethods": [
        "GET"
    ],
    "allowCredentials": false,
    "exposedHeaders": [
        "Akamai-Cors-Exposed"
    ],
    "preflightMaxAge": 86400
}

CorsSettings members

Member Type Required Description
allowCredentials Boolean Whether you allow credentialed HTTP requests to access your resources. Credentials may be cookies or TLS client certificates.
allowedHeaders Array The HTTP header names that you allow via the Access-Control-Allow-Headers header.
allowedMethods Array The HTTP methods that you allow via the Access-Control-Allow-Methods header, either GET, PUT, POST, DELETE, OPTIONS, PATCH, or HEAD.
allowedOrigins Array The origin hostnames that you allow via the Access-Control-Allow-Origin header. The wildcard (*) means all hostnames.
enabled Boolean Whether you enabled CORS for the endpoint.
exposedHeaders Array The headers that you expose via the Access-Control-Expose-Headers header. By exposing a header, you allow clients to access it.
preflightMaxAge Integer The maximum time in seconds for caching responses to preflight requests.

JwtSettings

Encapsulates information about JSON web token (JWT) validation settings configured for an endpoint. JWT is an open standard (RFC 7519) that defines a compact and self-contained method for securely transmitting JSON-encoded information between parties. It is often used for authentication purposes. You can configure JWT validation settings if the API Gateway product is in your contract.

Download schema: jwtDto-schema.json

Sample GET:

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

JwtSettings members

Member Type Required Description
enabled Boolean Whether you enabled JWT validation for the endpoint.
resources JwtSettings.resources Encapsulates information about JWT validation settings for each resource associated with an endpoint version. The resources are available through a map of resourceId keys.
settings JwtSettings.settings Encapsulates information about endpoint-level JWT settings.
JwtSettings.resources.{apiResourceId}: Encapsulates information about JWT settings configured for a resource.
enabled Boolean Whether you enabled JWT validation for the resource.
inheritsFromEndpoint Boolean Read-only. Whether the resource inherits the top-level JWT settings.
methods Array Read-only. The methods associated with the resource, either POST, GET, PUT, DELETE, HEAD, OPTIONS, or PATCH.
notes String, Null Read-only. The description of the resource.
path String Read-only. The URL path relative to the hostnames on which the resource resides.
JwtSettings.settings: Encapsulates information about endpoint-level JWT settings.
clockSkew Integer The allowed time difference in seconds between the server and client clocks when validating the exp and nbf JWT claims. The recommended value is 10.
location Enumeration The location of the JWT in incoming requests, either HEADER for a request header, COOKIE, or QUERY for a query parameter.
paramName String The name of the header, cookie, or query parameter that you specified for the JWT location.
validation JwtSettings.settings.validation, Null Encapsulates information about the JWT validation details, such as RSA public keys and JWT claims.
JwtSettings.settings.validation: Encapsulates information about the JWT validation details, such as RSA public keys and JWT claims.
claims JwtSettings.settings.validation.claims[] Encapsulates information about a reserved JWT claim.
rsaPublicKeyA JwtSettings.settings.validation.rsaPublicKeyA Encapsulates information about the primary RSA public key that you use for JWT validation.
rsaPublicKeyB JwtSettings.settings.validation.rsaPublicKeyB, Null Encapsulates information about the backup RSA public key for use during key rotations.
JwtSettings.settings.validation.claims[]: Encapsulates information about a reserved JWT claim.
name Enumeration The name of the reserved claim, either aud to identify the audience that the JWT is intended for, iss to identify the issuer of the JWT claim, sub to identify the subject of the JWT, exp to identify the expiration time on or after which the token is not accepted for processing, or nbf to identify the time before which the token is not accepted for processing. This value is not case-sensitive. For example, if you enter AUD for a value, the system automatically converts it to aud.
required Boolean Whether the presence of the JWT claim is required in incoming requests.
type Enumeration The data type of the JWT claim’s value, either ARRAY or STRING.
validate Boolean Whether to validate the value of the JWT claim at the edge.
value Array, String, Null The value of the JWT claim, represented as a string if it’s a single value, or as an array if there is more than one value. The array type only applies to the aud claim value.
JwtSettings.settings.validation.rsaPublicKeyA: Encapsulates information about the primary RSA public key that you use for JWT validation.
content String The content of the file containing the primary RSA key.
name String The name of the file containing the primary RSA key.
JwtSettings.settings.validation.rsaPublicKeyB: Encapsulates information about the backup RSA public key for use during key rotations.
content String The content of the file containing the backup RSA key.
name String The name of the file containing the backup RSA key.

Category

Encapsulates information about an endpoint category.

Download schema: categoryDto-schema.json

Sample GET response:

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

Category members

Member Type Required Description
apiCategoryDescription String The description of the category that you may use to tag related endpoints.
apiCategoryId Integer Read-only. The unique identifier for the category.
apiCategoryName String The unique-per-account name of the category. Any empty value reflects back as an __UNCATEGORIZED__ keyword.
createDate String Read-only. The ISO–6801 timestamp indicating when you created the category.
createdBy String The identifier for the user who created the category.
link String The location of the navigable resource within this API, for use by API clients. See Hypermedia for details.
lockVersion Number The identifier used for optimistic locking. See Concurrency Control for details.
updateDate String Read-only. The ISO–6801 timestamp indicating when you last modified the category.
updatedBy String The identifier for the user who last modified the category.
usageCount Integer The number of endpoints that share the category.

AcgPair

Encapsulates information about a pairing of contract and group under which you provision the security and delivery settings for an endpoint.

Download schema: aCGPickerRow-schema.json

Sample GET response:

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

AcgPair members

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

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

When the API encounters a problem, it responds with an object that adheres to the HTTP problem details standard. This sample shows an authorization error, where the type value is a non-navigable URI, and the instance may be useful if you need to communicate about the problem with your Akamai support representative:

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

HTTP status codes

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

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

Error types

The table below lists the common error types that you can encounter and their corresponding descriptions. Each name in the column on the left represents a string that appears after the following URL prefix in the type member: https://problems.luna.akamaiapis.net/api-definitions/error-types/.

Error type Description
activation-for-other-version-already-pending You cannot activate the endpoint version because another version’s activation is pending on the Akamai network.
activation-for-path-already-pending At least one base path and hostname combination that you specified for an endpoint is currently being activated on the Akamai network.
allow-any-domain-is-not-allowed For the CORS configuration, you cannot use a wildcard (*) in the allowedOrigins field when the allowCredentials field is set to true.
api-privacy-key-location-not-set For the API privacy configuration, to define an endpoint version as private, you must first specify the apiKeyLocation value for the endpoint version.
empty-contract You must specify a contract ID when creating or cloning an endpoint.
empty-group You must specify a Luna group ID when creating or cloning an endpoint.
empty-hosts You must include at least one hostname in the apiEndPointHosts array when creating or cloning an endpoint.
endpoint-name-not-unique An endpoint with the name that you specified already exists.
endpoint-invalid-basepath The basePath that you specified does not meet the syntactic requirements for a base path. Ensure that the base path starts with a forward slash (/) and does not end with one.
endpoint-invalid-host At least one element that you included in the apiEndPointHosts array does not meet the syntactic requirements outlined in RFC–952 and RFC–1123.
endpoint-path-already-active At least one base path and hostname combination that you specified is already active on the Akamai network.
endpoint-path-already-used At least one base path and hostname combination that you specified already exists in another endpoint configuration.
endpoint-version-already-active You cannot activate the endpoint version because it’s already active on the Akamai network.
endpoint-version-is-pending You cannot modify the endpoint version because it has pending changes that are being propagated to the Akamai network.
endpoint-version-locked You cannot modify the endpoint version because it has already been activated on the Akamai network.
endpoint-version-not-active You cannot deactivate the endpoint version because it is not currently active on the Akamai network.
endpoint-version-not-found You cannot modify the endpoint version because it does not exist.
greater-than-max The numerical JSON value is too large.
import-invalid-syntax The import file that you provided contains syntactic errors. For details on forming an API definition file, see either the Swagger specification or the RAML specification.
import-invalid-schema The import file that you provided is not a valid Swagger 2.0 or RAML 0.8 file. For details on forming an API definition file, see either the Swagger specification or the RAML specification.
import-hostnames-mismatch The hostnames in your imported API definition file do not match the hostnames configured for the endpoint. This is just to inform you that the system did not replace the original hostnames.
import-ref-not-found The importUrl that you specified for the import operation does not point to an API definition file.
invalid-category The apiCategoryId that you specified is not associated with any endpoints in the system.
invalid-contract The contract ID that you specified when creating or cloning an endpoint does not exist.
invalid-header The HTTP header value provided for the CORS configuration contains invalid characters.
invalid-http-method The JSON value is not an HTTP method name string. This is for JSON fields that expect HTTP methods for values.
invalid-json-value The JSON value does not meet the validation criteria for the corresponding JSON field.
invalid-origin The origin hostname does not meet the syntactic requirements outlined in RFC–952 and RFC–1123.
jwt-public-key-duplicated The primary and backup RSA keys uploaded for JWT validation purposes are identical.
less-than-min The numerical JSON value is too small.
multiple-type-parameters-not-supported The system only supports single-type parameters in imported API definitions files.
not-null The JSON value is null, and the corresponding JSON field does not accept null values.
raml-version-not-supported The system does not support the RAML version of your imported API definition file. The currently supported version is RAML 0.8.
required-param-missing The JSON value specified as required in the schema is missing from the request body.
resource-invalid-path The resourcePath that you specified does not meet the syntactic requirements for a path. Ensure that the resource path starts with a forward slash (/) and does not end with one.
resource-name-not-unique A resource with the name that you specified already exists.
resource-not-found The endpoint, version, or resource with the ID that you specified does not exist.
swagger-version-not-supported The system does not support the Swagger version of your imported API definition file. The currently supported version is Swagger 2.0.
type-mismatch The JSON value is of a different data type than expected in the corresponding JSON field.
unrecognized-json-field The JSON field is not present in the corresponding JSON schema.

Last modified: 8/7/2018