Register an endpoint

post

https://{hostname}/api-definitions/v2/endpoints

Creates the first version of an API endpoint configuration. You can specify the new endpoint's full set of resources. Alternatively, you can create them later either by modifying the endpoint object, or separately with the Create a resource operation. The endpoint's name needs to be unique within an account.

Query Params

accountSwitchKey

string

For customers who manage more than one account, this runs the operation from another account. The Identity and Access Management API provides a list of available account switch keys.

Body Params

An endpoint and its associated resources.

akamaiSecurityRestrictions

object | null

The App & API Protector security restrictions that you apply to an API. Note that you should only include these details in your requests if you're a App & API Protector customer.

apiCategoryIds

array of integers | null

The category identifiers that apply to the endpoint. The value is null for uncategorized endpoints.

apiCategoryIds

apiEndPointHosts

array of strings

required

length ≥ 1

The hostnames that may receive traffic for the endpoint. You need at least one hostname before activating the endpoint.

apiEndPointHosts*

apiEndPointName

string

required

The name of the endpoint, unique within the account.

apiEndPointScheme

string | null

enum

The URL scheme to which the endpoint may respond, either http, https, or http/https for both.

Allowed:

apiGatewayEnabled

boolean | null

Defaults to true

Whether the API Gateway product should be enabled for the endpoint. If null, the member is set to true.

apiSource

string | null

enum

Specifies if the API's data comes from API_DISCOVERY or was provided by the USER.

Allowed:

apiVersionInfo

object | null

A major API version. This refers to REST API versioning and is a different concept than the endpoint configuration versions you create at Akamai.

basePath

string | null

The URL path that serves as a root prefix for all resources' resourcePath values. This is / if empty. Don't append a / character to the path. If you specify null in the request or omit this member from the object, the JSON response reflects it as an empty string.

caseSensitive

boolean | null

Whether the URLs and parameters within the endpoint are case sensitive.

consumeType

string | null

enum

The content type the endpoint exchanges, either json, xml, urlencoded, json/xml/urlencoded, json/urlencoded, json/xml, or xml/urlencoded for multi-format APIs, any, or none. A null value is the same as a none string.

description

string | null

The description of the endpoint. If you specify null in the request or omit this member from the object, the JSON response reflects it as an empty string.

discoveredPiiIds

array of integers | null

Personally identifiable information (PII) in your API parameters discovered by the network.

discoveredPiiIds

isGraphQL

boolean

Whether the endpoint uses GraphQL to deliver structured content to clients.

matchPathSegmentParam

boolean | null

Defaults to true

Whether or not to include path segment parameters in match criteria, like the jsessionid portion of /ssocookie;jsessionid=434343.

positiveConstrainsEnabled

boolean | null

Specifies whether the App & API Protector firewall policies are enabled for the endpoint.

securityScheme

object | null

The key with which users may access the endpoint.

versionNumber

integer | null

The endpoint version number.

apiResources

array of objects | null

Resources assigned to the endpoint.

apiResources

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Response body

object

An endpoint and its associated resources.

akamaiSecurityRestrictions

object | null

The App & API Protector security restrictions that you apply to an API. Note that you should only include these details in your requests if you're a App & API Protector customer.

ALLOW_ONLY_SPEC_UNDEFINED_METHODS

integer

enum

Whether the API allows requests on undefined resources, but only for specific methods. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_BODY_PARAMS

integer

enum

Whether the API allows for requests with undefined parameters in body. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_COOKIE_PARAMS

integer

enum

Whether the API allows for requests with undefined parameters in cookies. These booleans override members in the Method object. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_HEADER_PARAMS

integer

enum

Whether the API allows for requests with undefined parameters in header. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_METHOD_DELETE

integer

enum

Whether the API allows requests on undefined resources using the DELETE method. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_METHOD_GET

integer

enum

Whether the API allows requests on undefined resources using the GET method. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_METHOD_HEAD

integer

enum

Whether the API allows requesting undefined resources using HEAD method. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_METHOD_OPTIONS

integer

enum

Whether the API allows requesting undefined resources using OPTIONS method. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_METHOD_PATCH

integer

enum

Whether the API allows requesting undefined resources using PATCH method. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_METHOD_POST

integer

enum

Whether the API allows requests on undefined resources using the POST method. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_METHOD_PUT

integer

enum

Whether the API allows requests on undefined resources using the PUT method. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_PARAMS

integer

enum

Whether the API allows requesting with undefined parameters. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_QUERY_PARAMS

integer

enum

Whether the API allows for requests with undefined parameters in query string. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_RESOURCES

integer

enum

Whether the API allows requests on undefined resources. Either 1 or 0 for yes or no.

1 0

ALLOW_UNDEFINED_SPEC_PARAMS

integer

enum

Whether the API allows requesting undefined resources, but only for specific locations. Either 1 or 0 for yes or no.

1 0

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

integer

enum

Whether to enforce the API request body and resource constraints as allowlists in your App & API Protector security policies. Either 1 for enabled security constraints, or 0 for disabled.

1 0

POSITIVE_SECURITY_VERSION

integer | null

enum

Whether to create the API with API Protection 2 or above. Either 1, 2 for enabled API Protection 2, or null for the legacy API.

1 2

RESPONSE_RESTRICTIONS_ENABLED

integer

enum

When set to 1, the API allows for responses with undefined parameters in the response body. Otherwise the value is 0.

1 0

apiCategoryIds

array of integers | null

The category identifiers that apply to the endpoint. The value is null for uncategorized endpoints.

apiEndPointHosts

array of strings

required

length ≥ 1

The hostnames that may receive traffic for the endpoint. You need at least one hostname before activating the endpoint.

apiEndPointId

integer | null

Read-only The unique identifier for the endpoint.

apiEndPointLocked

boolean | null

Read-only Whether the endpoint version is read-only.

apiEndPointName

string

required

The name of the endpoint, unique within the account.

apiEndPointScheme

string | null

enum

The URL scheme to which the endpoint may respond, either http, https, or http/https for both.

http https http/https

apiEndPointVersion

integer | null

Read-only The unique identifier for the endpoint version.

apiGatewayEnabled

boolean | null

Defaults to true

Whether the API Gateway product should be enabled for the endpoint. If null, the member is set to true.

apiSource

string | null

enum

Specifies if the API's data comes from API_DISCOVERY or was provided by the USER.

API_DISCOVERY USER

apiVersionInfo

object | null

A major API version. This refers to REST API versioning and is a different concept than the endpoint configuration versions you create at Akamai.

location

string

enum

required

The location of the API version value in an incoming request. Either HEADER, BASE_PATH, or QUERY parameter.

HEADER BASE_PATH QUERY

parameterName

string

The name of the header or query parameter that includes the API version value. This is applicable only if the corresponding location member is either HEADER or QUERY.

value

string

The expected API version value in an incoming request.

availableActions

array of strings | null

Read-only Available actions that you can perform on the endpoint depending on its versions' activation status. For possible values, see Endpoint.availableActions values.

DELETE CLONE_ENDPOINT COMPARE_ENDPOINT COMPARE_AAG_SETTINGS COMPARE_RAPID_SETTINGS EDIT_ENDPOINT_DEFINITION ACTIVATE_ON_STAGING ACTIVATE_ON_PRODUCTION DEACTIVATE_ON_STAGING DEACTIVATE_ON_PRODUCTION HIDE_ENDPOINT SHOW_ENDPOINT

basePath

string | null

caseSensitive

boolean | null

Whether the URLs and parameters within the endpoint are case sensitive.

clonedFromVersion

integer | null

Read-only For cloned endpoints, the unique identifier for the source endpoint version.

consumeType

string | null

enum

json xml urlencoded json/xml/urlencoded json/urlencoded json/xml xml/urlencoded any none

contractId

string | null

required

Read-only The unique identifier for the contract with Akamai under which you provisioned security and delivery settings for this API.

createDate

date-time | null

Read-only The ISO 8601 timestamp indicating when you created the endpoint.

createdBy

string | null

Read-only The identifier for the user who created the endpoint.

description

string | null

The description of the endpoint. If you specify null in the request or omit this member from the object, the JSON response reflects it as an empty string.

discoveredPiiIds

array of integers | null

Personally identifiable information (PII) in your API parameters discovered by the network.

endpointHidden

boolean | null

Read-only Specifies 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 | null

required

Read-only The unique identifier for the group in Control Center under which you provisioned security and delivery settings for this API.

isGraphQL

boolean

Whether the endpoint uses GraphQL to deliver structured content to clients.

lockVersion

integer

required

Read-only The identifier for the last modification of an endpoint version, used for optimistic locking. See Concurrency control for details.

matchPathSegmentParam

boolean | null

Defaults to true

Whether or not to include path segment parameters in match criteria, like the jsessionid portion of /ssocookie;jsessionid=434343.

positiveConstrainsEnabled

boolean | null

Specifies whether the App & API Protector firewall policies are enabled for the endpoint.

productionStatus

string | null

enum

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 was once active but is now inactive, 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.

PENDING ACTIVE DEACTIVATED FAILED

productionVersion

object | null

Read-only An endpoint version's activation status on the production network.

lastError

object | null

The last failed activation of the endpoint version.

status

string | null

enum

Read-only 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.

PENDING ACTIVE DEACTIVATED FAILED

timestamp

date-time | null

Read-only The ISO 8601 timestamp indicating the last update of the activation status.

versionNumber

integer | null

Read-only The endpoint version number.

protectedByApiKey

boolean

Read-only Whether you enabled API key protection for the endpoint version by making the version private.

responseConstraintsEnabled

boolean | null

Read-only Specifies whether response constraints are enforced for the endpoint. Note that if you enable response constraints but don't define the constraints, it behaves as if disabled.

securityScheme

object | null

The key with which users may access the endpoint.

securitySchemeDetail

object

The location of the API key.

securitySchemeType

string

enum

The type of security scheme implemented for the endpoint. The only valid value is apikey.

apikey

source

object | null

Read-only The import file used to create the endpoint.

apiVersion

string | null

Read-only The major version of the API defined in the import file.

specificationVersion

string | null

Read-only The version of the import file's specification.

type

string | null

enum

Read-only The specification of the import file you uploaded to create the endpoint version. Either SWAGGER or RAML.

SWAGGER RAML

stagingStatus

string | null

enum

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 was once active but is now inactive, 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.

PENDING ACTIVE DEACTIVATED FAILED

stagingVersion

object | null

Read-only An endpoint version's activation status on the staging network.

lastError

object | null

The last failed activation of the endpoint version.

status

string | null

enum

PENDING ACTIVE DEACTIVATED FAILED

timestamp

date-time | null

Read-only The ISO 8601 timestamp indicating the last update of the activation status.

versionNumber

integer | null

Read-only The endpoint version number.

updateDate

date-time | null

Read-only The ISO 8601 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 Specifies 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 | null

The endpoint version number.

apiResources

array of objects | null

Resources assigned to the endpoint.

apiResources

object

A resource assigned to an endpoint.

apiResourceClonedFromId

integer | null

For cloned resources, the unique identifier for the source resource.

apiResourceId

integer

The unique identifier for the resource.

apiResourceLogicId

integer

The unique identifier for the resource across all endpoint versions.

apiResourceMethodNameLists

array of strings

HTTP methods the resource may respond to.

apiResourceName

string

required

The name of the resource.

createDate

date-time

The ISO 8601 timestamp indicating when you created the resource.

createdBy

string

The identifier for the user who created the resource.

description

string | null

The description to clarify the resource's function within the API. If you specify null in the request or omit this member from the object, the JSON response reflects it as an empty string.

link

string | null

The location of the navigable resource within this API, for use by API clients.

lockVersion

integer

The identifier used for optimistic locking. See Concurrency control for details.

private

boolean

Whether the resource is private. API consumers can access private resources only if they identify with an appropriate API key.

resourcePath

string

required

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

date-time

The ISO 8601 timestamp indicating when you last modified the resource.

updatedBy

string

The identifier for the user who last modified the resource.

apiResourceMethods

array of objects

HTTP methods the resource may respond to.

apiResourceMethods

object

An HTTP method to which a resource may respond.

apiResourceMethod

string

enum

required

The core HTTP method to which the resource may respond, either GET, PUT, POST, DELETE, HEAD, PATCH, or OPTIONS.

GET PUT POST DELETE HEAD PATCH 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.

apiParameters

array of objects | null

Parameter objects assigned to the method.

apiParameters

object

A method's parameter.

apiChildParameters

array of objects

Child JSON members or XML elements for JSON or XML body type parameters.

apiChildParameters

object

A further nested endpoint object.

Has additional fields

apiParamLogicId

integer

Read-only The unique identifier for the parameter across all endpoint versions.

apiParameterId

integer

Read-only The unique identifier for the parameter.

apiParameterLocation

string

enum

required

The location of the parameter in an HTTP request, either query, header, path, cookie, or body for a JSON or XML body type parameter.

query header path cookie body

apiParameterName

string

required

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. If you specify an empty string in the request or omit this member from the object, the JSON response reflects it as null.

apiParameterRequired

boolean

required

Specifies whether the API user needs to specify the parameter. If the corresponding apiParameterLocation is path, set this member to true.

apiParameterRestriction

object | null

Restrictions and XML representation rules specified for the parameter.

apiParameterType

string

enum

required

The data type of the parameter, either string, integer, number, boolean, or json/xml for JSON or XML objects.

string integer number boolean json/xml

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.

arrayItemNullable

boolean | null

Indicates whether items in an array parameter can be null.

nullable

boolean | null

Defaults to false

Indicates whether the parameter value can be null.

pathParamLocationId

integer | null

The index of a segment that includes a path parameter in a resource path. For example, given a path \books\{bookId}, the books segment has index 0, and the path parameter {bookId} has index 1.

response

boolean

Whether the parameter is within a response type.

apiParameterContentType

string

enum

The content type of the parameter, either json, xml, any, or none. Only applicable for top-level body parameters.

json xml any none

Headers

object

Location

string

Relative URL for the created API endpoint.

Language

URL


xxxxxxxxxx
1
curl --request POST \
2
     --url https://hostname/api-definitions/v2/endpoints \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "apiEndPointHosts": []
8
}
9
'


xxxxxxxxxx
148
}
1
{
2
  "akamaiSecurityRestrictions": null,
3
  "apiCategoryIds": [
4
    2,
5
    7
6
  ],
7
  "apiEndPointHosts": [
8
    "bookstore.api.akamai.com"
9
  ],
10
  "apiEndPointId": 492375,
11
  "apiEndPointLocked": false,
12
  "apiEndPointName": "Bookstore API",
13
  "apiEndPointScheme": "http/https",
14
  "apiEndPointVersion": 574127,
15
  "apiGatewayEnabled": true,
16
  "apiResources": [
17
    {
18
      "apiResourceClonedFromId": null,
19
      "apiResourceId": 2926712,
20
      "apiResourceLogicId": 118435,
21
      "apiResourceMethods": [
22
        {
23
          "apiParameters": [
24
            {
25
              "apiChildParameters": [],
26
              "apiParamLogicId": 578116,
27
              "apiParameterId": 1212945,
28
              "apiParameterLocation": "path",
29
              "apiParameterName": "bookId",
30
              "apiParameterNotes": null,
31
              "apiParameterRequired": true,
32
              "apiParameterRestriction": null,
33
              "apiParameterType": "string",
34
              "apiResourceMethParamId": 494448,
35
              "array": false,
36
              "pathParamLocationId": null,
37
              "response": false
38
            }
39
          ],
40
          "apiResourceMethod": "GET",
41
          "apiResourceMethodId": 341591,
42
          "apiResourceMethodLogicId": 184404
43
        },

201New resource successfully created.

400Bad request. Invalid data input.

403Forbidden. You don't have access to the contract and group.