- Overview
- Resources
- API summary
- List endpoints
- Create an endpoint
- Clone an endpoint
- Create an endpoint from an API definition file
- List user entitlements
- Remove an endpoint
- Hide an endpoint
- Show an endpoint
- List versions
- Get a version summary
- Modify a version
- Remove a version
- Hide a version
- Show a version
- Update an endpoint from an API definition file
- Get a version
- Clone a version
- Activate a version
- Deactivate a version
- List resources
- Create a resource
- Get a resource
- Modify a resource
- Remove a resource
- List OAuth scopes
- Create an OAuth scope
- Update an OAauth scope
- Remove an OAuth scope
- Get cache settings
- Update cache settings
- Get GraphQL cache settings
- Update GraphQL cache settings
- Get GZIP settings
- Update GZIP settings
- Get CORS settings
- Update CORS settings
- Get JWT settings
- Update JWT settings
- Get API privacy settings
- Update API privacy settings
- Get error response settings
- Update error response settings
- Get an error response
- Update an error response
- Get OAuth scopes assignments
- Update OAuth scopes assignments
- List categories
- Create a category
- Get a category
- Modify a category
- Remove a category
- List contracts and groups
- List hostnames
- Data
- EndpointList
- Endpoint
- Endpoint.availableActions values
- VersionList
- VersionList.apiVersions
- Resource
- Method
- Parameter
- ImportResult
- Activation
- CacheSettings
- GraphQLCacheSettings
- ApiPrivacySettings
- GzipSettings
- CorsSettings
- ErrorSettings
- ErrorSettings.{errorType} values
- JwtSettings
- OauthScopeDefinition
- OauthScopesAssignments
- Category
- AcgPair
- CacheKey
- CacheKey.option values
- Duration
- ImportFile
- ApiVersionDetails
- Errors
API Endpoint Definition API v2
Wrap Kona Site Defender, Bot Manager Premier, and API Gateway features around an API endpoint.
Learn more:
PAPI Feature Catalog Reference,
rapidbehavior.Download this API’s RAML and JSON schema descriptors.
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 Akamai Control Center. 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 in 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, help API consumers troubleshoot errors more effectively, and enhance the overall performance of your API traffic. These features include API privacy, JSON web tokens (JWT), cross-origin resource sharing (CORS), caching, GraphQL caching, GZIP compression, error response customization, and OAuth scopes. 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 API Keys and Traffic 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
To configure this API for the first time:
Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this:
https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.To enable this API, choose the API service named API Definition, and set the access level to READ-WRITE.
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 Control Center:
WAF ConfigorWAF Adminfor endpoints, resources, versions, and security features management;API Gateway Administratorfor API Gateway delivery features;Bot Manager ConfigorBot Manager Featurefor 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 document distinguishes between three versioning concepts that you should consider independent of each other.
This most recent API v2 supersedes API Endpoints API v1. Akamai will continue to support v1 indefinitely, but the migration to this new version provides numerous benefits. It introduces internal version management for APIs configured with Akamai features, and it allows you to use the new API Gateway delivery settings.
This API allows you to register different major versions of your own APIs that you make available to your API consumers. These are versions in the REST API versioning sense, based on your APIs’ life cycle. By using this API, you can specify the version location and the expected version value in an incoming request. Based on these details, edge servers route the incoming request to the API URLs (hostname + base path) that you associated with the API version indicated in the request.
Finally, this API’s “version”-related operations allow you to internally maintain different minor versions of your registered API configurations, which lets you easily tweak the API Gateway features and tailor your API traffic as needed.
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, GraphQL caching, GZIP compression, error response customization, and OAuth scopes.
These are the objects you can interact with:
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, GraphQL caching, GZIP compression, error response customization, and OAuth scopes. Enabling these features can help you manage your APIs more efficiently, improve interoperability, provide useful guidelines to API consumers in case of errors, define the level of access to your APIs for external client apps, 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 Control Center 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/ |
| Create an endpoint | POST | /api-definitions/ |
| Clone an endpoint | POST | /api-definitions/ |
| Create an endpoint from an API definition file | POST | /api-definitions/ |
| List user entitlements | GET | /api-definitions/ |
| Remove an endpoint | DELETE | /api-definitions/ |
| Hide an endpoint | POST | /api-definitions/ |
| Show an endpoint | POST | /api-definitions/ |
| List versions | GET | /api-definitions/ |
| Get a version summary | GET | /api-definitions/ |
| Modify a version | PUT | /api-definitions/ |
| Remove a version | DELETE | /api-definitions/ |
| Hide a version | POST | /api-definitions/ |
| Show a version | POST | /api-definitions/ |
| Update an endpoint from an API definition file | POST | /api-definitions/ |
| Get a version | GET | /api-definitions/ |
| Clone a version | POST | /api-definitions/ |
| Activate a version | POST | /api-definitions/ |
| Deactivate a version | POST | /api-definitions/ |
| List resources | GET | /api-definitions/ |
| Create a resource | POST | /api-definitions/ |
| Get a resource | GET | /api-definitions/ |
| Modify a resource | PUT | /api-definitions/ |
| Remove a resource | DELETE | /api-definitions/ |
| Oauth Scopes | ||
| List OAuth scopes | GET | /api-definitions/ |
| Create an OAuth scope | POST | /api-definitions/ |
| Update an OAauth scope | PUT | /api-definitions/ |
| Remove an OAuth scope | DELETE | /api-definitions/ |
| Endpoint Settings | ||
| Get cache settings | GET | /api-definitions/ |
| Update cache settings | PUT | /api-definitions/ |
| Get GraphQL cache settings | GET | /api-definitions/ |
| Update GraphQL cache settings | PUT | /api-definitions/ |
| Get GZIP settings | GET | /api-definitions/ |
| Update GZIP settings | PUT | /api-definitions/ |
| Get CORS settings | GET | /api-definitions/ |
| Update CORS settings | PUT | /api-definitions/ |
| Get JWT settings | GET | /api-definitions/ |
| Update JWT settings | PUT | /api-definitions/ |
| Get API privacy settings | GET | /api-definitions/ |
| Update API privacy settings | PUT | /api-definitions/ |
| Get error response settings | GET | /api-definitions/ |
| Update error response settings | PUT | /api-definitions/ |
| Get an error response | GET | /api-definitions/ |
| Update an error response | PUT | /api-definitions/ |
| Get OAuth scopes assignments | GET | /api-definitions/ |
| Update OAuth scopes assignments | PUT | /api-definitions/ |
| Categories | ||
| List categories | GET | /api-definitions/ |
| Create a category | POST | /api-definitions/ |
| Get a category | GET | /api-definitions/ |
| Modify a category | PUT | /api-definitions/ |
| Remove a category | DELETE | /api-definitions/ |
| Contracts | ||
| List contracts and groups | GET | /api-definitions/ |
| List hostnames | GET | /api-definitions/ |
List endpoints
Lists 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/
Sample: /api-definitions/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| Optional query parameters | |||
category |
String | Site Delivery |
Filters endpoints by the specified apiCategoryName, including the __UNCATEGORIZED__ keyword. |
contains |
String | cloud security |
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. Run the Show an endpoint and Hide an endpoint operations to control which endpoints are listed. |
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 selecting 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
Object type: EndpointList
Download schema: apiEndpointListDto-schema.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"
}
]
}
Optionally set the
contractIdandgroupIdquery parameters to filter results provisioned under a specific pairing of contract and group.Optionally filter results to a specific
category, or setcontainsto search on text.If you want to affect how output sorts, set the
sortByquery parameter to eithernameorupdateDate, or setsortOrdertoascordesc.If you want to modify pagination, set the
pageSizequery parameter for the number of records per page, and the overallpagenumber.If you want to change the default version preference and return the last activated version for each endpoint, set the
versionPreferencevalue toACTIVATED_FIRST.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
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 must be unique within an account.
POST /api-definitions/
Content-Type: application/json
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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",
"isGraphQL": true,
"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
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.json
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
}
If you don’t already have the
contractIdandgroupIdmembers, run the List contracts and groups operation.Select the appropriate pairing of contract and group under which you want to provision the new endpoint. Store the
contractIdandgroupIdvalues.If you want to tag the new endpoint with optional categories, run the List categories operation and store the appropriate
apiCategoryIdvalues from the array of Category objects.Build an Endpoint object, specifying the
contractIdandgroupIdmembers, theapiEndPointHostsmember, and a uniqueapiEndPointName.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
Creates an endpoint as a clone from the specified source endpoint ID and version.
POST /api-definitions/
Content-Type: application/json
Object type: Endpoint
Download schema: apiEndpointCloneDto-schema.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
Headers:
Location: /api-definitions/v2/endpoints/123/versions/2
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.If you don’t already have the
contractIdandgroupIdmembers, run the List contracts and groups operation.Select the appropriate pairing of contract and group under which you want to provision the new endpoint. Store the
contractIdandgroupIdvalues.Build an Endpoint object, specifying the
contractIdandgroupIdmembers, theapiEndpointIdof the source endpoint, theversionNumberof the version you want to clone, thebasePath,apiEndPointHosts, and a uniqueapiEndPointNamefor the new endpoint.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
Imports an API definition file and creates a new endpoint based on the file contents. You can run this operation in two ways. To POST JSON data, see Make a JSON request to create an endpoint from an API definition file. To make a form request using the parameters listed below, see Make a form request to create an endpoint from an API definition file.
POST /api-definitions/
Content-Type: application/json
Object type: ImportFile
Download schema: importFileDto-schema.json
Request body:
{
"importFileFormat": "swagger",
"importFileSource": "BODY_BASE64",
"importFileContent": "ewogICAgInN3YWdnZXIiOiAiMi4wIiwKICAgICJpbmZvIjogewogICAgICAgICJ0aXRsZSI6ICJ3ZWF0aGVyLmdvdiBBUEkgMjAxOC0wNS0xNSAxMTo0MjoxOCIsCiAgICAgICAgImRlc2NyaXB0aW9uIjogIlJhcGlkUmVJbXBvcnRfMjAxOC4wNS4xNC4wNy40OS4zOSIsCiAgICAgICAgInZlcnNpb24iOiAiMS4wLjAiCiAgICB9LAogICAgImhvc3QiOiAid3d3LnBldHN0b3JlLmNvbSIsCiAgICAic2NoZW1lcyI6IFsKICAgICAgICAiaHR0cCIKICAgIF0sCiAgICAiYmFzZVBhdGgiOiAiL3Byb2R1Y3Rpb24iLAogICAgInBhdGhzIjogewogICAgICAgICIvYWxsLzIwMCI6IHsKICAgICAgICAgICAgImdldCI6IHsKICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJMaXN0IEl0ZW0gbnVtYmVycyIsCiAgICAgICAgICAgICAgICAib3BlcmF0aW9uSWQiOiAiaXRlbUdFVCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgR0VUIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0sCiAgICAgICAgICAgICJwb3N0IjogewogICAgICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogIkxpc3QgSXRlbSBudW1iZXJzIiwKICAgICAgICAgICAgICAgICJvcGVyYXRpb25JZCI6ICJpdGVtUG9zdCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgUG9zdCIsCiAgICAgICAgICAgICAgICAgICAgICAgICJzY2hlbWEiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAidHlwZSI6ICJhcnJheSIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAiaXRlbXMiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIiRyZWYiOiAiIy9kZWZpbml0aW9ucy9pbmxpbmVfcmVzcG9uc2VfMjAwIgogICAgICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAgICAgICAicHV0IjogewogICAgICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogIkxpc3QgSXRlbSBudW1iZXJzIiwKICAgICAgICAgICAgICAgICJvcGVyYXRpb25JZCI6ICJpdGVtUG9zdCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgUG9zdCIsCiAgICAgICAgICAgICAgICAgICAgICAgICJzY2hlbWEiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAidHlwZSI6ICJhcnJheSIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAiaXRlbXMiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIiRyZWYiOiAiIy9kZWZpbml0aW9ucy9pbmxpbmVfcmVzcG9uc2VfMjAwIgogICAgICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAgICAgICAicGF0Y2giOiB7CiAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiTGlzdCBJdGVtIG51bWJlcnMiLAogICAgICAgICAgICAgICAgIm9wZXJhdGlvbklkIjogIml0ZW1Qb3N0IiwKICAgICAgICAgICAgICAgICJwcm9kdWNlcyI6IFsKICAgICAgICAgICAgICAgICAgICAiYXBwbGljYXRpb24vanNvbiIKICAgICAgICAgICAgICAgIF0sCiAgICAgICAgICAgICAgICAicmVzcG9uc2VzIjogewogICAgICAgICAgICAgICAgICAgICIyMDAiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJBbiBlbnRpdHkgY29ycmVzcG9uZGluZyB0byB0aGUgcmVxdWVzdGVkIHJlc291cmNlIGlzIHNlbnQgaW4gdGhlIHJlc3BvbnNlIGZvciBQYXRjaCIsCiAgICAgICAgICAgICAgICAgICAgICAgICJzY2hlbWEiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAidHlwZSI6ICJhcnJheSIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAiaXRlbXMiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIiRyZWYiOiAiIy9kZWZpbml0aW9ucy9pbmxpbmVfcmVzcG9uc2VfMjAwIgogICAgICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAgICAgICAiZGVsZXRlIjogewogICAgICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogIkxpc3QgSXRlbSBudW1iZXJzIiwKICAgICAgICAgICAgICAgICJvcGVyYXRpb25JZCI6ICJpdGVtUG9zdCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgRGVsZXRlIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICB9LAogICAgICAgICIvZ2V0LzIwMCI6IHsKICAgICAgICAgICAgImdldCI6IHsKICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJMaXN0IEl0ZW0gbnVtYmVycyIsCiAgICAgICAgICAgICAgICAib3BlcmF0aW9uSWQiOiAiaXRlbUdFVCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgR0VUIGZvciAvZ2V0LzIwMCBwYXRoIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICB9LAogICAgICAgICIvR0VULzIwMCI6IHsKICAgICAgICAgICAgImdldCI6IHsKICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJMaXN0IEl0ZW0gbnVtYmVycyIsCiAgICAgICAgICAgICAgICAib3BlcmF0aW9uSWQiOiAiaXRlbUdFVCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgR0VUIGZvciAvR0VULzIwMCBwYXRoIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICB9CiAgICB9LAogICAgInNlY3VyaXR5RGVmaW5pdGlvbnMiOiB7CiAgICAgICAgImFwaV9rZXkiOiB7CiAgICAgICAgICAgICJ0eXBlIjogImFwaUtleSIsCiAgICAgICAgICAgICJuYW1lIjogImFwaV9rZXlfYmFzaWMiLAogICAgICAgICAgICAiaW4iOiAicXVlcnkiCiAgICAgICAgfQogICAgfQp9",
"contractId": "1",
"groupId": 1
}
POST /api-definitions/
Content-Type: multipart/form-data
See Parameters for details on upload content.
| Parameter | Type | Sample | Description |
|---|---|---|---|
| Form parameters | |||
importFileFormat |
Enumeration | raml |
The format of the API definition file, either raml (0.8) or swagger (2.0 or 3.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
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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,
"isGraphQL": 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
},
"apiVersionInfo": {
"location": "HEADER",
"parameterName": "Version",
"value": "v1"
},
"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
}
Make a JSON request to create an endpoint from an API definition file
This section shows you how to create an endpoint from an API definition file
by submitting an application/json request. If instead you would like to submit
a multipart/form-data request to create an endpoint, see Make a form request to create an endpoint from an API definition file.
If you don’t already have the obligatory
contractIdandgroupIdmembers, run the List contracts and groups operation.Select the appropriate pairing of contract and group under which you want to provision the new endpoint. Store the
contractIdandgroupIdvalues.Build an ImportFile object, specifying the
contractIdandgroupIdmembers, theimportFileFormat, and theimportFileSource. Depending on theimportFileSource, specify either theimportFileContentorimportUrl.POST the object to
/.api-definitions/ v2/ endpoints/ files
The response Endpoint object reflects the newly created
endpoint based on your API definition file. You can access the
newly created endpoint at the URL specified in the Location response
header.
Make a form request to create an endpoint from an API definition file
This section shows you how to create an endpoint from an API definition file
by submitting a multipart/form-data request (see RFC 2388 for details).
If instead you would like to submit an application/json request to create an endpoint, see Make a JSON request to create an endpoint from an API definition file.
If you don’t already have the obligatory
contractIdandgroupIdmembers, run the List contracts and groups operation.Select the appropriate pairing of contract and group under which you want to provision the new endpoint. Store the
contractIdandgroupIdvalues.Prepare an API definition file and set the
importFileFormattoramlorswagger.Assign the filename as the
importFile.Optionally embed the API definition within a ZIP archive, in which case reset the definition filename as
rootand the name of the archive asimportFile.Optionally make the definition or archive file available on the web at an
importUrl.Prepare a
multipart/form-datarequest specifying the fields listed in Parameters. Specify either animportFileorimportUrl, and make sure to specify therootif you are uploading a ZIP archive.Make a form data POST request to
/.api-definitions/ v2/ endpoints/ files
The response Endpoint object reflects the newly created
endpoint based on your API definition file. You can access the
newly created endpoint at the URL specified in the Location response
header.
List user entitlements
Lists user entitlements based on your assigned permissions. It helps you
determine if your user identity associated with the API client can run various other operations to modify data.
See Getting started for details on setting up the API client with the appropriate level of access.
This operation’s array 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/
Status 200
application/json
Download schema: userEntitlementsDto-schema.json
Response body:
[
"API_READ",
"API_WRITE",
"API_VERSIONING",
"API_FEATURES"
]
Remove an endpoint
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/
Sample: /api-definitions/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL parameters | |||
apiEndPointId |
Integer | 12892 |
The unique identifier for the endpoint. |
Status 204
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.Make a DELETE request to
/.api-definitions/ v2/ endpoints/ {apiEndPointId}
A 204 response confirms the Endpoint object has been deleted.
Hide an endpoint
Hides an endpoint and all its versions. You can
only hide an endpoint with no active versions on the staging or production
network. You cannot activate or delete versions of a hidden endpoint. A hidden endpoint
appears in the List endpoints operation’s response object by default,
or when you set the operation’s show query parameter to ONLY_HIDDEN.
Running this operation affects the endpoint listing in the API Definitions user interface.
POST /api-definitions/
Sample: /api-definitions/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL parameters | |||
apiEndPointId |
Integer | 12892 |
The unique identifier for the endpoint. |
Status 200
application/json
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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,
"isGraphQL": 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
},
"apiVersionInfo": {
"location": "HEADER",
"parameterName": "Version",
"value": "v1"
},
"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
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.Make a POST request to
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ hide
The response reflects back the hidden Endpoint object.
Show an endpoint
Reveals a hidden endpoint and all its versions.
A revealed endpoint appears in the List endpoints operation’s
response object by default, or when you set the operation’s show query parameter to ONLY_VISIBLE.
Running this operation affects the endpoint listing in the API Definitions user interface.
POST /api-definitions/
Sample: /api-definitions/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL parameters | |||
apiEndPointId |
Integer | 12892 |
The unique identifier for the endpoint. |
Status 200
application/json
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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,
"isGraphQL": 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
},
"apiVersionInfo": {
"location": "HEADER",
"parameterName": "Version",
"value": "v1"
},
"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
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.Make a POST request to
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ show
The response reflects back the revealed Endpoint object.
List versions
Returns all versions of an endpoint.
GET /api-definitions/
Sample: /api-definitions/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL parameters | |||
apiEndPointId |
Integer | 12892 |
The unique identifier for the endpoint. |
Status 200
application/json
Object type: VersionList
Download schema: apiEndpointVersionListDto-schema.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
}
]
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.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
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/
Sample: /api-definitions/
| 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
Download schema: apiVersionSummaryDto-schema.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"
]
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.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
Updates details about an endpoint version that has never been activated on the staging or production network. By modifying the Endpoint object, you can configure the endpoint’s security settings and other top-level metadata, or modify the endpoint’s entire set of resources as an alternative to separate calls to Modify a resource. Note that the corresponding Get a version operation you need to run to GET the data uses a different URL.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Run the Get a version operation for the complete representation of the object.
Modify the returned Endpoint object.
PUT the object to this URL:
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}
A 200 response confirms success, and the response object reflects your modifications.
Remove a version
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. Each endpoint version you create has a permanent number that cannot be reused even if you remove a version. A removed endpoint version no longer appears in the List versions operation’s response object.
DELETE /api-definitions/
Sample: /api-definitions/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL parameters | |||
apiEndPointId |
Integer | 12892 |
The unique identifier for the endpoint. |
versionNumber |
Integer | 1 |
The endpoint version number. |
Status 204
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Make a DELETE request to
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}
A 204 response confirms the version has been deleted.
Hide a version
Hides an endpoint version. You can only hide
inactive or deactivated versions. You cannot activate or delete hidden versions.
A hidden endpoint version appears in the List versions
operation’s response object with the hidden parameter set to true.
Running this operation affects the version listing in the API Definitions user interface.
POST /api-definitions/
Sample: /api-definitions/
| 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
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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,
"isGraphQL": 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
},
"apiVersionInfo": {
"location": "HEADER",
"parameterName": "Version",
"value": "v1"
},
"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
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.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
Reveals a hidden endpoint version.
A revealed endpoint version appears in the List versions
operation’s response object with the hidden parameter set to false.
Running this operation affects the version listing in the API Definitions user interface.
POST /api-definitions/
Sample: /api-definitions/
| 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
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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,
"isGraphQL": 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
},
"apiVersionInfo": {
"location": "HEADER",
"parameterName": "Version",
"value": "v1"
},
"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
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.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
Imports an API definition file with details about an endpoint. Unlike Create an endpoint from an API definition file, this operation does not create a new endpoint, but updates details of an existing endpoint. You can run this operation in two ways. To POST JSON data, see Make a JSON request to update an endpoint from an API definition file. To make a form request using the parameters below, see Make a form request to update an endpoint from an API definition file. Once you submit the POST 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/
Sample: /api-definitions/
Content-Type: application/json
Object type: ImportFile
Download schema: importFileDto-schema.json
Request body:
{
"importFileFormat": "swagger",
"importFileSource": "BODY_BASE64",
"importFileContent": "ewogICAgInN3YWdnZXIiOiAiMi4wIiwKICAgICJpbmZvIjogewogICAgICAgICJ0aXRsZSI6ICJ3ZWF0aGVyLmdvdiBBUEkgMjAxOC0wNS0xNSAxMTo0MjoxOCIsCiAgICAgICAgImRlc2NyaXB0aW9uIjogIlJhcGlkUmVJbXBvcnRfMjAxOC4wNS4xNC4wNy40OS4zOSIsCiAgICAgICAgInZlcnNpb24iOiAiMS4wLjAiCiAgICB9LAogICAgImhvc3QiOiAid3d3LnBldHN0b3JlLmNvbSIsCiAgICAic2NoZW1lcyI6IFsKICAgICAgICAiaHR0cCIKICAgIF0sCiAgICAiYmFzZVBhdGgiOiAiL3Byb2R1Y3Rpb24iLAogICAgInBhdGhzIjogewogICAgICAgICIvYWxsLzIwMCI6IHsKICAgICAgICAgICAgImdldCI6IHsKICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJMaXN0IEl0ZW0gbnVtYmVycyIsCiAgICAgICAgICAgICAgICAib3BlcmF0aW9uSWQiOiAiaXRlbUdFVCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgR0VUIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0sCiAgICAgICAgICAgICJwb3N0IjogewogICAgICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogIkxpc3QgSXRlbSBudW1iZXJzIiwKICAgICAgICAgICAgICAgICJvcGVyYXRpb25JZCI6ICJpdGVtUG9zdCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgUG9zdCIsCiAgICAgICAgICAgICAgICAgICAgICAgICJzY2hlbWEiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAidHlwZSI6ICJhcnJheSIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAiaXRlbXMiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIiRyZWYiOiAiIy9kZWZpbml0aW9ucy9pbmxpbmVfcmVzcG9uc2VfMjAwIgogICAgICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAgICAgICAicHV0IjogewogICAgICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogIkxpc3QgSXRlbSBudW1iZXJzIiwKICAgICAgICAgICAgICAgICJvcGVyYXRpb25JZCI6ICJpdGVtUG9zdCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgUG9zdCIsCiAgICAgICAgICAgICAgICAgICAgICAgICJzY2hlbWEiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAidHlwZSI6ICJhcnJheSIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAiaXRlbXMiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIiRyZWYiOiAiIy9kZWZpbml0aW9ucy9pbmxpbmVfcmVzcG9uc2VfMjAwIgogICAgICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAgICAgICAicGF0Y2giOiB7CiAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiTGlzdCBJdGVtIG51bWJlcnMiLAogICAgICAgICAgICAgICAgIm9wZXJhdGlvbklkIjogIml0ZW1Qb3N0IiwKICAgICAgICAgICAgICAgICJwcm9kdWNlcyI6IFsKICAgICAgICAgICAgICAgICAgICAiYXBwbGljYXRpb24vanNvbiIKICAgICAgICAgICAgICAgIF0sCiAgICAgICAgICAgICAgICAicmVzcG9uc2VzIjogewogICAgICAgICAgICAgICAgICAgICIyMDAiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJBbiBlbnRpdHkgY29ycmVzcG9uZGluZyB0byB0aGUgcmVxdWVzdGVkIHJlc291cmNlIGlzIHNlbnQgaW4gdGhlIHJlc3BvbnNlIGZvciBQYXRjaCIsCiAgICAgICAgICAgICAgICAgICAgICAgICJzY2hlbWEiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAidHlwZSI6ICJhcnJheSIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAiaXRlbXMiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIiRyZWYiOiAiIy9kZWZpbml0aW9ucy9pbmxpbmVfcmVzcG9uc2VfMjAwIgogICAgICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAgICAgICAiZGVsZXRlIjogewogICAgICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogIkxpc3QgSXRlbSBudW1iZXJzIiwKICAgICAgICAgICAgICAgICJvcGVyYXRpb25JZCI6ICJpdGVtUG9zdCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgRGVsZXRlIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICB9LAogICAgICAgICIvZ2V0LzIwMCI6IHsKICAgICAgICAgICAgImdldCI6IHsKICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJMaXN0IEl0ZW0gbnVtYmVycyIsCiAgICAgICAgICAgICAgICAib3BlcmF0aW9uSWQiOiAiaXRlbUdFVCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgR0VUIGZvciAvZ2V0LzIwMCBwYXRoIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICB9LAogICAgICAgICIvR0VULzIwMCI6IHsKICAgICAgICAgICAgImdldCI6IHsKICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJMaXN0IEl0ZW0gbnVtYmVycyIsCiAgICAgICAgICAgICAgICAib3BlcmF0aW9uSWQiOiAiaXRlbUdFVCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgR0VUIGZvciAvR0VULzIwMCBwYXRoIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICB9CiAgICB9LAogICAgInNlY3VyaXR5RGVmaW5pdGlvbnMiOiB7CiAgICAgICAgImFwaV9rZXkiOiB7CiAgICAgICAgICAgICJ0eXBlIjogImFwaUtleSIsCiAgICAgICAgICAgICJuYW1lIjogImFwaV9rZXlfYmFzaWMiLAogICAgICAgICAgICAiaW4iOiAicXVlcnkiCiAgICAgICAgfQogICAgfQp9",
"contractId": "1",
"groupId": 1
}
POST /api-definitions/
Sample: /api-definitions/
Content-Type: multipart/form-data
See Parameters for details on upload content.
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL parameters | |||
apiEndPointId |
Integer | 12892 |
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 or 3.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
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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,
"isGraphQL": 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
},
"apiVersionInfo": {
"location": "HEADER",
"parameterName": "Version",
"value": "v1"
},
"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
}
Make a JSON request to update an endpoint from an API definition file
This section shows you how to update an endpoint from an API definition file
by submitting an application/json request. If instead you would like to submit
a multipart/form-data request to update an endpoint, see Make a form request to update an endpoint from an API definition file.
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Build an ImportFile object, specifying the
importFileFormatandimportFileSource. Depending on theimportFileSource, specify either theimportFileContentorimportUrl.POST the object to
/.api-definitions/ v2/ endpoints/ file Use the POST response JSON as request data for the Modify a version PUT operation.
A 200 response confirms success, and the response object reflects your modifications.
Make a form request to update an endpoint from an API definition file
This section shows you how to update an endpoint from an API definition file
by submitting a multipart/form-data request (see RFC 2388 for details).
If instead you would like to submit an application/json request to update an endpoint, see Make a JSON request to update an endpoint from an API definition file.
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Prepare an API definition file and set the
importFileFormattoramlorswagger.Assign the filename as the
importFile.Optionally embed the API definition within a ZIP archive, in which case reset the definition filename as
rootand the name of the archive asimportFile.Optionally make the definition or archive file available on the web at an
importUrl.Prepare a
multipart/form-datarequest specifying the fields listed in Parameters. Specify either animportFileorimportUrl, and make sure to specify therootif you are uploading a ZIP archive.Make a form data POST request to
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ file Use the POST response JSON as request data for the Modify a version PUT operation.
A 200 response confirms success, and the response object reflects your modifications.
Get a version
Returns an endpoint version. Use this operation’s Endpoint response object when modifying an endpoint version through Modify a version. Do not use Get a version summary for the Modify a version operation.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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,
"isGraphQL": 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
},
"apiVersionInfo": {
"location": "HEADER",
"parameterName": "Version",
"value": "v1"
},
"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
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.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
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/
Sample: /api-definitions/
| 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
Object type: Endpoint
Download schema: apiEndpointWithResourceDto-schema.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
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.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
Activates an endpoint version on the staging or production network. If another version of the endpoint is already active on the specified network, that version automatically deactivates and the newly activated version takes its place. If an active version of another endpoint shares any hostnames with the version you activate, the API 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/
Sample: /api-definitions/
Content-Type: application/json
Object type: Activation
Download schema: activationDto-schema.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
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Build an Activation object, specifying the
networkswhere you activate the version and the email addresses for thenotificationRecipients.POST the object to
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ activate
A 200 response confirms a successful activation.
Deactivate a version
Deactivates an endpoint version on the staging or production network. A deactivated endpoint version no longer serves traffic through the Akamai network.
POST /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: Activation
Download schema: activationDto-schema.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
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Build an Activation object, specifying the
networkswhere you deactivate the version and the email addresses for thenotificationRecipients.POST the object to
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ deactivate
A 200 response confirms a successful deactivation.
List resources
Lists all resources associated with an endpoint version.
You can use the apiResourceId of each returned resource to modify resources individually through
the Modify a resource operation, or run the Modify a version
operation to batch-modify a group of resources.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: Resource
Download schema: apiResourceMethParamsDto-schema.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
}
]
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Make a GET request to
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ resources
The response is an array of Resource objects.
Create a resource
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/
Sample: /api-definitions/
Content-Type: application/json
Object type: Resource
Download schema: apiResourceMethParamsDto-schema.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
Object type: Resource
Download schema: apiResourceMethParamsDto-schema.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
}
]
}
]
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Build a Resource object, specifying a unique
apiResourceNameandresourcePath.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
Returns a resource within an endpoint version.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: Resource
Download schema: apiResourceMethParamsDto-schema.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
}
]
}
]
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.If you don’t already have an
apiResourceIdvalue, run the List resources operation.Select the appropriate resource from the returned array and store its
apiResourceIdvalue.Make a GET request to
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ resources/ {apiResourceId}
The response is a Resource object.
Modify a resource
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/
Sample: /api-definitions/
Content-Type: application/json
Object type: Resource
Download schema: apiResourceMethParamsDto-schema.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
Object type: Resource
Download schema: apiResourceMethParamsDto-schema.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
}
]
}
]
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.If you don’t already have an
apiResourceIdvalue, run the List resources operation.Select the appropriate resource from the returned array and store its
apiResourceIdvalue.Run the Get a resource operation for the complete representation of the object.
Modify the returned Resource object.
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
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/
Sample: /api-definitions/
| 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
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.If you don’t already have an
apiResourceIdvalue, run the List resources operation.Select the appropriate resource from the returned array and store its
apiResourceIdvalue.Make a DELETE request to
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ resources/ {apiResourceId}
A 204 response confirms the resource has been deleted.
List OAuth scopes
Lists the OAuth scopes available to the API client.
GET /api-definitions/
Status 200
application/json
Download schema: oauthScopeList-schema.json
Response body:
[
{
"name": "Books:Read",
"description": "View your books"
},
{
"name": "Calendar:Read",
"description": "View your calendar"
}
]
Create an OAuth scope
Creates an OAuth scope. It lets you provide a meaningful description clarifying the scope. The description of a scope appears on the second consent page in the Manage API Definitions application in Control Center, where resource owners grant client apps access to their data. By providing a meaningful description, you make sure that a resource owner fully understands the extent to which a client app will be able to access their resources. To assign the scope to an endpoint version and its associated resources, you can run the Update OAuth scopes assignments operation.
POST /api-definitions/
Content-Type: application/json
Object type: OauthScopeDefinition
Download schema: oauthScope-schema.json
Request body:
{
"name": "Books:Read",
"description": "View your books"
}
Status 201
application/json
Object type: OauthScopeDefinition
Download schema: oauthScope-schema.json
Response body:
{
"name": "Books:Read",
"description": "View your books"
}
Update an OAauth scope
Updates an OAuth scope. It lets you provide a meaningful description clarifying the scope. The description of a scope appears on the second consent page in the Manage API Definitions application in Control Center, where resource owners grant client apps access to their data. By providing a meaningful description, you make sure that a resource owner fully understands the extent to which a client app will be able to access their resources. To assign the scope to an endpoint version and its associated resources, you can run the Update OAuth scopes assignments operation.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: OauthScopeDefinition
Download schema: oauthScope-schema.json
Request body:
{
"name": "Books:Read",
"description": "View your books"
}
| Parameter | Type | Sample | Description |
|---|---|---|---|
| Required query parameters | |||
name |
String | Books:Read |
The name of the OAuth scope. |
Status 200
application/json
Object type: OauthScopeDefinition
Download schema: oauthScope-schema.json
Response body:
{
"name": "Books:Read",
"description": "View your books"
}
Remove an OAuth scope
Removes an OAuth scope if it isn’t assigned to any endpoint version that is active or pending activation on the staging or production network.
DELETE /api-definitions/
Sample: /api-definitions/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| Required query parameters | |||
name |
String | Books:Read |
The name of the OAuth scope. |
Status 204
Get cache settings
Returns the caching settings configured for an endpoint version and its associated resources.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: CacheSettings
Download schema: cacheSettingsDto-schema.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 an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.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
Updates the caching settings configured for an endpoint version and its associated resources.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: CacheSettings
Download schema: cacheSettingsDto-schema.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
Object type: CacheSettings
Download schema: cacheSettingsDto-schema.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:
Run the List endpoints operation.
Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.Run the List versions operation.
Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.
To modify endpoint-level cache settings:
Run the Get cache settings operation for the complete representation of the object.
Modify the returned CacheSettings object.
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:
Run the List resources operation.
Select the appropriate resource from the returned array and store its
apiResourceIdvalue.If the
apiResourceIdis present in the CacheSettings object’sresources, modify theCacheSettings.resources.{apiResourceId}value.If the
apiResourceIdis absent from the CacheSettings object’sresources, create a newCacheSettings.resources.{apiResourceId}object under that key.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 GraphQL cache settings
Returns the GraphQL caching settings configured for an endpoint version. You can run this operation if you are taking part in the API Gateway 1.1 beta program.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: GraphQLCacheSettings
Download schema: graphQLDto-schema.json
Response body:
{
"detectError": false,
"nestingLevel": null,
"queryParamName": "query",
"maxQuerySize": null,
"maxAge": {
"duration": 40,
"unit": "SECONDS"
},
"bodyParamName": "query",
"downstreamCaching": {
"markAsPrivate": false,
"headers": "CACHE_CONTROL_AND_EXPIRES",
"maxAge": null,
"lifetime": "SMALLER_VALUE",
"option": "NOT_ALLOW_CACHING"
},
"cacheOrigin": false,
"cacheResponseOnError": false,
"enabled": true
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Make a GET request to
/api-definitions/.v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ settings/ graphql
The response is a GraphQLCacheSettings object that displays GraphQL caching settings for the requested endpoint version.
Update GraphQL cache settings
Updates the GraphQL caching settings configured for an endpoint version. You can run this operation if you are taking part in the API Gateway 1.1 beta program.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: GraphQLCacheSettings
Download schema: graphQLDto-schema.json
Request body:
{
"detectError": false,
"nestingLevel": null,
"queryParamName": "query",
"maxQuerySize": null,
"maxAge": {
"duration": 40,
"unit": "SECONDS"
},
"bodyParamName": "query",
"downstreamCaching": {
"markAsPrivate": false,
"headers": "CACHE_CONTROL_AND_EXPIRES",
"maxAge": null,
"lifetime": "SMALLER_VALUE",
"option": "NOT_ALLOW_CACHING"
},
"cacheOrigin": false,
"cacheResponseOnError": false,
"enabled": 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
Object type: GraphQLCacheSettings
Download schema: graphQLDto-schema.json
Response body:
{
"detectError": false,
"nestingLevel": null,
"queryParamName": "query",
"maxQuerySize": null,
"maxAge": {
"duration": 40,
"unit": "SECONDS"
},
"bodyParamName": "query",
"downstreamCaching": {
"markAsPrivate": false,
"headers": "CACHE_CONTROL_AND_EXPIRES",
"maxAge": null,
"lifetime": "SMALLER_VALUE",
"option": "NOT_ALLOW_CACHING"
},
"cacheOrigin": false,
"cacheResponseOnError": false,
"enabled": true
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Run the Get GraphQL cache settings operation for the complete representation of the object.
Modify the returned GraphQLCacheSettings object.
PUT the object back to the same URL as the GET:
/api-definitions/.v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ settings/ graphql
A 200 response confirms success, and the response object reflects your modifications.
Get GZIP settings
Returns the GZIP compression settings configured for an endpoint version.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: GzipSettings
Download schema: gzipDto-schema.json
Response body:
{
"compressResponse": "ALWAYS"
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.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
Updates the GZIP compression settings configured for an endpoint version.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: GzipSettings
Download schema: gzipDto-schema.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
Object type: GzipSettings
Download schema: gzipDto-schema.json
Response body:
{
"compressResponse": "ALWAYS"
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Run the Get GZIP settings operation for the complete representation of the object.
Modify the returned GzipSettings object.
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
Returns the cross-origin resource sharing (CORS) settings configured for an endpoint version.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: CorsSettings
Download schema: corsDto-schema.json
Response body:
{
"enabled": true,
"allowedOrigins": [
"*"
],
"allowedHeaders": [
"Akamai-Cors-Allowed"
],
"allowedMethods": [
"GET"
],
"allowCredentials": false,
"exposedHeaders": [
"Akamai-Cors-Exposed"
],
"preflightMaxAge": 86400
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.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
Updates the cross-origin resource sharing (CORS) settings configured for an endpoint version.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: CorsSettings
Download schema: corsDto-schema.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
Object type: CorsSettings
Download schema: corsDto-schema.json
Response body:
{
"enabled": true,
"allowedOrigins": [
"*"
],
"allowedHeaders": [
"Akamai-Cors-Allowed"
],
"allowedMethods": [
"GET"
],
"allowCredentials": false,
"exposedHeaders": [
"Akamai-Cors-Exposed"
],
"preflightMaxAge": 86400
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Run the Get CORS settings operation for the complete representation of the object.
Modify the returned CorsSettings object.
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
Returns the JWT validation settings configured for an endpoint version and its associated resources.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: JwtSettings
Download schema: jwtDto-schema.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"
},
{
"name": "scope",
"validate": true,
"required": false,
"value": [
"read",
"write",
"delete"
],
"type": "ARRAY"
}
],
"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 an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.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
Updates the JWT validation settings configured for an endpoint version and its associated resources.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: JwtSettings
Download schema: jwtDto-schema.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"
},
{
"name": "scope",
"validate": true,
"required": false,
"value": [
"read",
"write",
"delete"
],
"type": "ARRAY"
}
],
"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
Object type: JwtSettings
Download schema: jwtDto-schema.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"
},
{
"name": "scope",
"validate": true,
"required": false,
"value": [
"read",
"write",
"delete"
],
"type": "ARRAY"
}
],
"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:
Run the List endpoints operation.
Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.Run the List versions operation.
Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.
To modify endpoint-level JWT validation settings:
Run the Get JWT settings operation for the complete representation of the object.
Modify the returned JwtSettings object.
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:
Run the List resources operation.
Select the appropriate resource from the returned array and store its
apiResourceIdvalue.If the
apiResourceIdis present in the JwtSettings object’sresources, modify theJwtSettings.resources.{apiResourceId}value.If the
apiResourceIdis absent from the JwtSettings object’sresources, create a newJwtSettings.resources.{apiResourceId}object under that key.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
Returns the API privacy settings configured for an endpoint version and its associated resources.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: ApiPrivacySettings
Download schema: apiPrivacySettingsDto-schema.json
Response body:
{
"public": false,
"resources": {
"2874264": {
"public": false,
"path": "/path/to/resource10/get/200",
"methods": {
"GET": {
"public": false,
"inheritsFromEndpoint": false
},
"POST": {
"public": false,
"inheritsFromEndpoint": false
},
"PUT": {
"public": false,
"inheritsFromEndpoint": false
},
"HEAD": {
"public": false,
"inheritsFromEndpoint": false
},
"PATCH": {
"public": false,
"inheritsFromEndpoint": false
},
"OPTIONS": {
"public": false,
"inheritsFromEndpoint": false
},
"DELETE": {
"public": false,
"inheritsFromEndpoint": false
}
},
"inheritsFromEndpoint": false,
"notes": "resource10 notes"
}
}
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.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
Updates the API privacy settings configured for an endpoint version and its associated resources.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: ApiPrivacySettings
Download schema: apiPrivacySettingsDto-schema.json
Request body:
{
"public": false,
"resources": {
"2874264": {
"public": false,
"path": "/path/to/resource10/get/200",
"methods": {
"GET": {
"public": false,
"inheritsFromEndpoint": false
},
"POST": {
"public": false,
"inheritsFromEndpoint": false
},
"PUT": {
"public": false,
"inheritsFromEndpoint": false
},
"HEAD": {
"public": false,
"inheritsFromEndpoint": false
},
"PATCH": {
"public": false,
"inheritsFromEndpoint": false
},
"OPTIONS": {
"public": false,
"inheritsFromEndpoint": false
},
"DELETE": {
"public": false,
"inheritsFromEndpoint": false
}
},
"inheritsFromEndpoint": false,
"notes": "resource10 notes"
}
}
}
| 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
Object type: ApiPrivacySettings
Download schema: apiPrivacySettingsDto-schema.json
Response body:
{
"public": false,
"resources": {
"2874264": {
"public": false,
"path": "/path/to/resource10/get/200",
"methods": {
"GET": {
"public": false,
"inheritsFromEndpoint": false
},
"POST": {
"public": false,
"inheritsFromEndpoint": false
},
"PUT": {
"public": false,
"inheritsFromEndpoint": false
},
"HEAD": {
"public": false,
"inheritsFromEndpoint": false
},
"PATCH": {
"public": false,
"inheritsFromEndpoint": false
},
"OPTIONS": {
"public": false,
"inheritsFromEndpoint": false
},
"DELETE": {
"public": false,
"inheritsFromEndpoint": false
}
},
"inheritsFromEndpoint": false,
"notes": "resource10 notes"
}
}
}
If you don’t already have apiEndpointId and versionNumber values:
Run the List endpoints operation.
Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.Run the List versions operation.
Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.
To modify endpoint-level API privacy settings:
Run the Get API privacy settings operation for the complete representation of the object.
Modify the returned ApiPrivacySettings object.
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:
Run the List resources operation.
Select the appropriate resource from the returned array and store its
apiResourceIdvalue.If the
apiResourceIdis present in the ApiPrivacySettings object’sresources, modify theApiPrivacySettings.resources.{apiResourceId}value.If the
apiResourceIdis absent from the ApiPrivacySettings object’sresources, create a newApiPrivacySettings.resources.{apiResourceId}object under that key.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.
Get error response settings
Returns the error response settings configured for an endpoint version. You can run this operation if you are taking part in the API Gateway 1.1 beta program.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: ErrorSettings
Download schema: errorResponsesDto-schema.json
Response body:
{
"API_KEY_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The API key you provided does not exist.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"API_KEY_FORBIDDEN": {
"overrideDefaults": false,
"statusCode": 403,
"body": "{\"title\":\"The API key you provided does not have access to the requested resource.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"QUOTA_EXCEEDED": {
"overrideDefaults": false,
"statusCode": 429,
"body": "{\"title\":\"The quota limit for the API key you provided has been exceeded during the current time period.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"JWT_SIGNATURE_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The JSON web signature in JWT did not pass the JWT validation.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"JWT_CLAIM_VALUE_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The JWT claim value did not pass the JWT validation.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
}
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Make a GET request to
/api-definitions/.v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ settings/ error-responses
The response is a ErrorSettings object that displays error response settings for the requested endpoint version.
Update error response settings
Updates the error response settings configured for an endpoint version. You can run this operation if you are taking part in the API Gateway 1.1 beta program.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: ErrorSettings
Download schema: errorResponsesDto-schema.json
Request body:
{
"API_KEY_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The API key you provided does not exist.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"API_KEY_FORBIDDEN": {
"overrideDefaults": false,
"statusCode": 403,
"body": "{\"title\":\"The API key you provided does not have access to the requested resource.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"QUOTA_EXCEEDED": {
"overrideDefaults": false,
"statusCode": 429,
"body": "{\"title\":\"The quota limit for the API key you provided has been exceeded during the current time period.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"JWT_SIGNATURE_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The JSON web signature in JWT did not pass the JWT validation.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"JWT_CLAIM_VALUE_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The JWT claim value did not pass the JWT validation.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
}
}
| 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
Object type: ErrorSettings
Download schema: errorResponsesDto-schema.json
Response body:
{
"API_KEY_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The API key you provided does not exist.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"API_KEY_FORBIDDEN": {
"overrideDefaults": false,
"statusCode": 403,
"body": "{\"title\":\"The API key you provided does not have access to the requested resource.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"QUOTA_EXCEEDED": {
"overrideDefaults": false,
"statusCode": 429,
"body": "{\"title\":\"The quota limit for the API key you provided has been exceeded during the current time period.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"JWT_SIGNATURE_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The JSON web signature in JWT did not pass the JWT validation.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"JWT_CLAIM_VALUE_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The JWT claim value did not pass the JWT validation.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
}
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Run the Get error response settings operation for the complete representation of the object.
Modify the returned ErrorSettings object.
PUT the object back to the same URL as the GET:
/api-definitions/.v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ settings/ error-responses
A 200 response confirms success, and the response object reflects your modifications.
Get an error response
Returns a customizable error response of the selected type. You can run this operation if you are taking part in the API Gateway 1.1 beta program.
GET /api-definitions/
Sample: /api-definitions/
| 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. |
type |
Enumeration | API_KEY_INVALID |
The type of the customizable error response. For possible values, see ErrorSettings.{errorType} values. |
Status 200
application/json
Download schema: errorResponseDto-schema.json
Response body:
{
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The API key you provided does not exist.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Set the
typeURL parameter to the value that represents the error response you want to return.Make a GET request to
/api-definitions/.v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ settings/ error-responses/ {type}
The response’s ErrorSettings.{errorType} object shows the details of the requested error.
Update an error response
Updates a customizable error response of the selected type. You can run this operation if you are taking part in the API Gateway 1.1 beta program.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Download schema: errorResponseDto-schema.json
Request body:
{
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The API key you provided does not exist.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
}
| 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. |
type |
Enumeration | API_KEY_INVALID |
The type of the customizable error response. For possible values, see ErrorSettings.{errorType} values. |
Status 200
application/json
Download schema: errorResponseDto-schema.json
Response body:
{
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The API key you provided does not exist.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Run the Get an error response operation and set the
typeto the appropriate value.Modify the returned ErrorSettings.{errorType} object.
PUT the modified object back to the same URL as the GET:
/api-definitions/.v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ settings/ error-responses/ {type}
A 200 response confirms success, and the response object reflects your modifications.
Get OAuth scopes assignments
Returns the assignments of OAuth scopes configured for an endpoint version and its associated resources. You can run this operation if you are taking part in the API Gateway 1.1 beta program.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: OauthScopesAssignments
Download schema: oauthDto-schema.json
Response body:
{
"enabled": true,
"resources": {
"100": {
"path": "/calendar",
"methods": {
"GET": {
"scopes": [
"read:calendar"
],
"notes": null
},
"POST": {
"scopes": [
"write:calendar"
],
"notes": null
}
},
"scopes": [
"admin:calendar"
],
"notes": null
},
"101": {
"path": "/mail",
"methods": {
"GET": {
"scopes": [
"read:mail"
],
"notes": null
},
"POST": {
"scopes": [],
"notes": null
},
"PUT": {
"scopes": [],
"notes": null
},
"DELETE": {
"scopes": [],
"notes": null
}
},
"scopes": [],
"notes": null
},
"102": {
"path": "/contacts",
"methods": {
"GET": {
"scopes": [],
"notes": null
},
"PUT": {
"scopes": [],
"notes": null
},
"DELETE": {
"scopes": [],
"notes": null
}
},
"scopes": [
"contacts"
],
"notes": "Core contacts API resource"
}
}
}
If you don’t already have an
apiEndpointIdvalue, run the List endpoints operation.Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.If you don’t already have a
versionNumbervalue, run the List versions operation.Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Make a GET request to
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ settings/ oauth
The response is an OAuthScopesAssignments object that displays OAuth settings for the requested endpoint version and its associated resources.
Update OAuth scopes assignments
Updates the assignments of OAuth scopes configured for an endpoint version and its associated resources. You can run this operation if you are taking part in the API Gateway 1.1 beta program.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: OauthScopesAssignments
Download schema: oauthDto-schema.json
Request body:
{
"enabled": true,
"resources": {
"100": {
"path": "/calendar",
"methods": {
"GET": {
"scopes": [
"read:calendar"
],
"notes": null
},
"POST": {
"scopes": [
"write:calendar"
],
"notes": null
}
},
"scopes": [
"admin:calendar"
],
"notes": null
},
"101": {
"path": "/mail",
"methods": {
"GET": {
"scopes": [
"read:mail"
],
"notes": null
},
"POST": {
"scopes": [],
"notes": null
},
"PUT": {
"scopes": [],
"notes": null
},
"DELETE": {
"scopes": [],
"notes": null
}
},
"scopes": [],
"notes": null
},
"102": {
"path": "/contacts",
"methods": {
"GET": {
"scopes": [],
"notes": null
},
"PUT": {
"scopes": [],
"notes": null
},
"DELETE": {
"scopes": [],
"notes": null
}
},
"scopes": [
"contacts"
],
"notes": "Core contacts API resource"
}
}
}
| 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
Object type: OauthScopesAssignments
Download schema: oauthDto-schema.json
Response body:
{
"enabled": true,
"resources": {
"100": {
"path": "/calendar",
"methods": {
"GET": {
"scopes": [
"read:calendar"
],
"notes": null
},
"POST": {
"scopes": [
"write:calendar"
],
"notes": null
}
},
"scopes": [
"admin:calendar"
],
"notes": null
},
"101": {
"path": "/mail",
"methods": {
"GET": {
"scopes": [
"read:mail"
],
"notes": null
},
"POST": {
"scopes": [],
"notes": null
},
"PUT": {
"scopes": [],
"notes": null
},
"DELETE": {
"scopes": [],
"notes": null
}
},
"scopes": [],
"notes": null
},
"102": {
"path": "/contacts",
"methods": {
"GET": {
"scopes": [],
"notes": null
},
"PUT": {
"scopes": [],
"notes": null
},
"DELETE": {
"scopes": [],
"notes": null
}
},
"scopes": [
"contacts"
],
"notes": "Core contacts API resource"
}
}
}
If you don’t already have apiEndpointId and versionNumber values:
Run the List endpoints operation.
Select the appropriate endpoint from the returned array and store its
apiEndpointIdvalue.Run the List versions operation.
Select the appropriate endpoint version from the returned array and store its
versionNumbervalue.Run the Get OAuth scopes assignments operation for the complete representation of the object.
Copy the returned OAuthScopesAssignments object for future use.
Run the List resources operation.
Select the appropriate resource from the returned array and store its
apiResourceIdvalue.If the
apiResourceIdis present in the OAuthScopesAssignments object’sresources, modify theOAuthAssignments .resources.{apiResourceId}value.If the
apiResourceIdis absent from the OAuthScopesAssignments object’sresources, create a newOAuthAssignments .resources.{apiResourceId}object under that key.
To modify OAuth scopes for the resource:
- PUT the full object back to the same URL as the GET:
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ settings/ oauth
To modify OAuth scopes for a method within the resource:
Select the appropriate HTTP method associated with the resource you picked.
Modify the OauthScopesAssignments.resources.{apiResourceId}.methods.{apiResourceMethod} object.
PUT the full object back to the same URL as the GET:
/.api-definitions/ v2/ endpoints/ {apiEndPointId}/ versions/ {versionNumber}/ settings/ oauth
A 200 response confirms success, and the response object reflects your modifications.
List categories
Lists all categories available to tag endpoints and optionally indicates the number of endpoints tagged under each category.
GET /api-definitions/
Sample: /api-definitions/
| 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
Object type: Category
Download schema: categoryDtos-schema.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
}
]
Optionally set the
withUsageInfoquery parameter totrueif you want the listed categories to show the number of endpoints they apply to.Make a GET request to
/.api-definitions/ v2/ categories{?withUsageInfo}
The response is an array of Category objects.
Create a category
Creates a category that you can use to tag endpoints. The
request’s apiCategoryName needs to be unique per account.
POST /api-definitions/
Content-Type: application/json
Object type: Category
Download schema: categoryDto-schema.json
Request body:
{
"apiCategoryName": "Web Performance",
"apiCategoryDescription": "web performance apis"
}
Status 201
application/json
Headers:
Location: /api-definitions/v2/api-categories/123
Object type: Category
Download schema: categoryDto-schema.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"
}
Build a Category object, specifying a unique
apiCategoryName.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
Returns a specific category that you can use to tag endpoints.
GET /api-definitions/
Sample: /api-definitions/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL parameters | |||
apiCategoryId |
Integer | 13 |
The unique identifier for the category. |
Status 200
application/json
Object type: Category
Download schema: categoryDto-schema.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"
}
If you don’t already have an
apiCategoryIdvalue, run the List categories operation.Select the appropriate category from the returned array and store its
apiCategoryIdvalue.Make a GET request to
/.api-definitions/ v2/ categories/ {apiCategoryId}
The response is a Category object.
Modify a category
Updates a category’s description or unique name.
PUT /api-definitions/
Sample: /api-definitions/
Content-Type: application/json
Object type: Category
Download schema: categoryDto-schema.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
Object type: Category
Download schema: categoryDto-schema.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"
}
If you don’t already have an
apiCategoryIdvalue, run the List categories operation.Select the appropriate category from the returned array and store its
apiCategoryIdvalue.Run the Get a category operation for the complete representation of the object.
Modify the returned Category object.
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
Removes an unassigned category. If you assigned the category to at least one endpoint, the operation returns a 403 error.
DELETE /api-definitions/
Sample: /api-definitions/
| Parameter | Type | Sample | Description |
|---|---|---|---|
| URL parameters | |||
apiCategoryId |
Integer | 13 |
The unique identifier for the category. |
Status 204
If you don’t already have an
apiCategoryIdvalue of the appropriate Category object, run the List categories operation.Select the appropriate category from the returned array and store its
apiCategoryIdvalue.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 Control Center 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/
Status 200
application/json
Object type: AcgPair
Download schema: aCGPickerRows-schema.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
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/
Sample: /api-definitions/
| 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
Download schema: hosts-schema.json
Response body:
[
"www.akamai.com",
"www3.akamai.com"
]
Run the List contracts and groups operation.
From the response array, choose the appropriate pairing of contract and group, and store its
contractIdandgroupIdvalues.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 in requests, or always present in responses, even if 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 either triggers an error, or is ignored. |
EndpointList
Contains information about a collection of requested endpoints.
Download schema:
apiEndpointListDto-schema.json
EndpointList members
| Member | Type | Required | Description |
|---|---|---|---|
EndpointList: Contains information about a collection of requested endpoints. |
|||
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
Contains information about an endpoint to clone.
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 | ||||
|---|---|---|---|---|---|---|---|---|
Endpoint: Contains information about an endpoint to clone. |
||||||||
akamai |
Endpoint. |
✗ | ○ | Contains 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. | ||||
api |
Boolean, Null | ✗ | ○ | Read-only. Whether the endpoint version is read-only. | ||||
apiEndPointName |
String | ✓ | ✓ | The name of the endpoint, unique within the account. | ||||
api |
Enumeration, Null | ✗ | ○ | The URL scheme to which the endpoint may respond, either http, https, or http/https for both. |
||||
apiResources |
Resource Array | ✗ | ○ | The list of Resource objects associated with the endpoint. | ||||
apiVersionInfo |
Endpoint. |
✗ | ○ | Contains information about a major API version. This refers to REST API versioning and is a different concept than the endpoint configuration versions you create at Akamai. | ||||
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. |
||||
cloned |
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 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 | ✗ | ○ | 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. |
||||
production |
Endpoint. |
✗ | ○ | Read-only. Contains information about an endpoint version’s activation status on the production network. | ||||
protected |
Boolean | ✗ | ○ | Read-only. Whether you enabled API key protection for the endpoint version by making the version private. | ||||
securityScheme |
Endpoint. |
✗ | ○ | Contains 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. |
✗ | ○ | Read-only. Contains 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: Contains 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.apiVersionInfo: Contains information about 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 |
Enumeration | ✗ | ✓ | The location of the API version value in an incoming request. Either HEADER, BASE_PATH, or QUERY parameter. |
||||
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. | ||||
Endpoint.productionVersion: Contains 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: Contains information about the key with which users may access the endpoint. |
||||||||
security |
Endpoint. |
✗ | ○ | Contains information about the location of the API key. | ||||
security |
Enumeration | ✗ | ○ | The type of security scheme implemented for the endpoint. The only valid value is apikey. |
||||
Endpoint.securityScheme.securitySchemeDetail: Contains 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: Contains 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
These 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
Contains 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 |
|---|---|---|---|
VersionList: Contains information about all versions of an endpoint. |
|||
apiEndPointId |
Integer | ○ | The unique identifier for the endpoint. |
apiEndPointName |
String | ○ | The name of the endpoint, unique within the account. |
apiVersions |
Version |
○ | Contains information about each endpoint version within a collection. |
VersionList.apiVersions[]: Contains information about each endpoint version within a collection. |
|||
api |
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
These 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 delivery 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 delivery 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 delivery settings. |
Resource
Contains 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 |
|---|---|---|---|
Resource: Contains information about a Resource associated with an Endpoint. |
|||
api |
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. |
api |
Integer, Null | ○ | Read-only. The unique identifier for the resource across all endpoint versions. |
api |
Method Array | ○ | The list of Method objects that represent HTTP methods the resource may respond to. |
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. |
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
Contains information about an HTTP method to which a resource may respond.
Download schema:
apiMethodParametersDto-schema.json
Method members
| Member | Type | Required | Description |
|---|---|---|---|
Method: Contains information about an HTTP method to which a resource may respond. |
|||
apiParameters |
Parameter Array | ○ | The list of Parameter objects associated with the method. |
api |
Enumeration | ✓ | The core HTTP method to which the resource may respond, either get, put, post, delete, head, patch, or options. |
api |
Integer, Null | ○ | Read-only. The unique identifier for the resource’s allowed method. |
api |
Integer, Null | ○ | Read-only. The unique identifier for the resource’s method across all endpoint versions. |
Parameter
Contains information about a method’s parameter.
Download schema:
apiParameterDto-schema.json
Parameter members
| Member | Type | Required | Description |
|---|---|---|---|
Parameter: Contains information about a method’s parameter. |
|||
api |
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. |
api |
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. |
api |
String, Null | ○ | The description to clarify the parameter’s function. |
api |
Boolean | ✓ | Whether the parameter is required. If the corresponding apiParameterLocation is path, set this member to true. |
api |
Parameter. |
○ | Contains 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. |
api |
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: Contains information about restrictions and XML representation rules specified for the parameter. |
|||
arrayRestriction |
Parameter. |
○ | Contains information about array restrictions for array type parameters. Define this object only if you enabled the corresponding array member. |
length |
Parameter. |
○ | Contains information about length restrictions for string type parameters. |
number |
Parameter. |
○ | Contains information about range restrictions for number type parameters. |
rangeRestriction |
Parameter. |
○ | Contains information about range restrictions for integer type parameters. |
xml |
Parameter. |
○ | Contains information about an XML representation of a JSON-encoded parameter. |
Parameter.apiParameterRestriction.arrayRestriction: Contains 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: Contains 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: Contains 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: Contains 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: Contains 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
Contains 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 |
|---|---|---|---|
ImportResult: Contains information about a result of an import operation, including endpoint details and a list of potential issues. |
|||
api |
Endpoint | ○ | Contains information about the imported endpoint. |
problems |
Import |
○ | The list of problems that occurred during the import, such as schema errors or unsupported property warnings. |
ImportResult.problems[]: The list of problems that occurred during the import, such as schema errors or unsupported property warnings. |
|||
detail |
String | ○ | The detailed error message. |
errors |
Import |
○ | 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
Contains 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 |
|---|---|---|---|
Activation: Contains information about an endpoint version activation. |
|||
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. |
notification |
Array | ○ | The email addresses where the system sends the activation notification. |
CacheSettings
Contains 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 |
|---|---|---|---|
CacheSettings: Contains 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. |
|||
cacheKey |
Cache |
○ | Contains information about cache key settings. |
downstream |
Cache |
○ | Contains 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 |
Cache |
○ | Contains information about error caching settings. |
maxAge |
Duration | ○ | Contains 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 |
Cache |
○ | Contains 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.downstreamCaching: Contains 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 |
Duration | ✓ | Contains 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.errorCaching: Contains information about error caching settings. |
|||
enabled |
Boolean | ✓ | Whether you enabled error caching. |
maxAge |
Duration | ✓ | Contains information about the maximum duration to keep error responses in a cache. |
preserveStale |
Boolean, Null | ✓ | Whether to preserve stale responses when the origin is unreachable and content revalidation is not possible. |
CacheSettings.resources: Contains information about caching settings for each resource associated with an endpoint version. The resources are available through a map of resourceId keys. |
|||
cacheKey |
Cache |
○ | Contains information about cache key settings. |
inherits |
Boolean | ○ | Whether the resource inherits the top-level API caching settings. |
maxAge |
Duration | ○ | Contains information about the maximum duration of keeping content in a cache. If set, overwrites the max age instructions set at the endpoint level. |
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. |
{apiResourceId} |
Cache |
○ | Contains information about caching settings configured for a resource within your API. |
CacheSettings.resources.{apiResourceId}: Contains 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. |
GraphQLCacheSettings
Contains information about GraphQL caching settings configured for an endpoint. GraphQL caching settings specify properties such as the query and body parameters that contain GraphQL queries, maximum age of cached content, and downstream cacheability. You can configure GraphQL caching settings if the API Gateway product is in your contract and if you are taking part in the API Gateway 1.1 beta program.
Download schema:
graphQLDto-schema.json
Sample GET:
{
"detectError": false,
"nestingLevel": null,
"queryParamName": "query",
"maxQuerySize": null,
"maxAge": {
"duration": 40,
"unit": "SECONDS"
},
"bodyParamName": "query",
"downstreamCaching": {
"markAsPrivate": false,
"headers": "CACHE_CONTROL_AND_EXPIRES",
"maxAge": null,
"lifetime": "SMALLER_VALUE",
"option": "NOT_ALLOW_CACHING"
},
"cacheOrigin": false,
"cacheResponseOnError": false,
"enabled": true
}
GraphQLCacheSettings members
| Member | Type | Required | Description |
|---|---|---|---|
GraphQLCacheSettings: Contains information about GraphQL caching settings configured for an endpoint. GraphQL caching settings specify properties such as the query and body parameters that contain GraphQL queries, maximum age of cached content, and downstream cacheability. You can configure GraphQL caching settings if the API Gateway product is in your contract and if you are taking part in the API Gateway 1.1 beta program. |
|||
bodyParamName |
String, Null | ○ | The name of the JSON body parameter that contains a GraphQL query in an incoming POST request. If the request’s content type is application/json, this is the name of the key that contains a GraphQL query as its value. If the request’s content type is application/graphql, edge servers treat the entire request body as a GraphQL query. |
cache |
Boolean, Null | ○ | Whether edge servers should cache the response to a GraphQL-type request in case errors are present in the response body. |
detectError |
Boolean, Null | ○ | By default, GraphQL queries return partial data if only a portion of a request fails. In such cases, status codes do not indicate errors. Instead, an errors array in a response body contains error details. This indicates whether edge servers should inspect the response body for the errors array. |
downstream |
Graph |
○ | Contains 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 GraphQL caching for the endpoint. |
maxAge |
Duration | ○ | Contains information about the maximum duration to keep content in a cache. |
maxQuerySize |
Integer | ○ | The maximum size of the query. A post body or a get response can’t exceed 4 KBs. |
nestingLevel |
String | ○ | The number of supported nesting levels within a query. The maximum number is 100. |
queryParamName |
String, Null | ○ | The name of the query parameter that contains a GraphQL query in an incoming GET or POST request. |
GraphQLCacheSettings.downstreamCaching: Contains 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 |
Duration | ✓ | Contains 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. |
ApiPrivacySettings
Contains 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:
{
"public": false,
"resources": {
"2874264": {
"public": false,
"path": "/path/to/resource10/get/200",
"methods": {
"GET": {
"public": false,
"inheritsFromEndpoint": false
},
"POST": {
"public": false,
"inheritsFromEndpoint": false
},
"PUT": {
"public": false,
"inheritsFromEndpoint": false
},
"HEAD": {
"public": false,
"inheritsFromEndpoint": false
},
"PATCH": {
"public": false,
"inheritsFromEndpoint": false
},
"OPTIONS": {
"public": false,
"inheritsFromEndpoint": false
},
"DELETE": {
"public": false,
"inheritsFromEndpoint": false
}
},
"inheritsFromEndpoint": false,
"notes": "resource10 notes"
}
}
}
ApiPrivacySettings members
| Member | Type | Required | Description |
|---|---|---|---|
ApiPrivacySettings: Contains 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. |
|||
public |
Boolean | ✓ | Whether the endpoint is public, that is, accessible without an API key. |
resources |
Api |
○ | Contains information about each resource’s privacy settings. |
ApiPrivacySettings.resources: Contains information about each resource’s privacy settings. |
|||
{apiResourceId} |
Api |
○ | Contains information about a resource’s privacy settings. |
ApiPrivacySettings.resources.{apiResourceId}: Contains information about a resource’s privacy settings. |
|||
inherits |
Boolean | ○ | Read-only. Whether the resource inherits the top-level API privacy settings. |
methods |
Api |
○ | 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. |
ApiPrivacySettings.resources.{apiResourceId}.methods: The methods associated with the resource, either POST, GET, PUT, DELETE, HEAD, OPTIONS, or PATCH. |
|||
{GET\|POST\|PUT\|DELETE\|HEAD\|OPTIONS\|PATCH} |
Api |
○ | Contains information about a method’s privacy settings. |
ApiPrivacySettings.resources.{apiResourceId}.methods.{GET|POST|PUT|DELETE|HEAD|OPTIONS|PATCH}: Contains information about a method’s privacy settings. |
|||
inherits |
Boolean | ○ | Read-only. Whether the method inherits the top-level API privacy settings. |
public |
Boolean | ○ | Whether the method is public, that is, accessible without an API key. |
GzipSettings
Contains 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 |
|---|---|---|---|
GzipSettings: Contains 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. |
|||
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
Contains 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 |
|---|---|---|---|
CorsSettings: Contains 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. |
|||
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. |
ErrorSettings
Contains information about error response settings configured for an endpoint. If an inbound client request fails, API Gateway returns a default error response with a JSON-formatted description and a status code. You can customize the descriptions, status codes, and headers of selected error responses to help API consumers identify the cause of an error and troubleshoot effectively. You can configure error response settings if the API Gateway product is in your contract and if you are taking part in the API Gateway 1.1 beta program.
Download schema:
errorResponsesDto-schema.json
Sample GET:
{
"API_KEY_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The API key you provided does not exist.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"API_KEY_FORBIDDEN": {
"overrideDefaults": false,
"statusCode": 403,
"body": "{\"title\":\"The API key you provided does not have access to the requested resource.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"QUOTA_EXCEEDED": {
"overrideDefaults": false,
"statusCode": 429,
"body": "{\"title\":\"The quota limit for the API key you provided has been exceeded during the current time period.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"JWT_SIGNATURE_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The JSON web signature in JWT did not pass the JWT validation.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
},
"JWT_CLAIM_VALUE_INVALID": {
"overrideDefaults": false,
"statusCode": 401,
"body": "{\"title\":\"The JWT claim value did not pass the JWT validation.\" }",
"headers": [
{
"name": "Content-Type",
"value": "application/problem+json"
}
]
}
}
ErrorSettings members
| Member | Type | Required | Description |
|---|---|---|---|
ErrorSettings: Contains information about error response settings configured for an endpoint. If an inbound client request fails, API Gateway returns a default error response with a JSON-formatted description and a status code. You can customize the descriptions, status codes, and headers of selected error responses to help API consumers identify the cause of an error and troubleshoot effectively. You can configure error response settings if the API Gateway product is in your contract and if you are taking part in the API Gateway 1.1 beta program. |
|||
{errorType} |
Error |
○ | Contains error responses, keyed by different error types. For possible values, see ErrorSettings.{errorType} values. |
ErrorSettings.{errorType}: Contains error responses, keyed by different error types. For possible values, see ErrorSettings.{errorType} values. |
|||
body |
String, Null | ○ | The response body to return in case of the error. The value should have the proper formatting to reflect the content type. For example, in case of a JSON body format, enclose the text in curly brackets ({}). |
headers |
Error |
○ | The list of HTTP headers to return in case of the error. By default, API Gateway returns the Content-Type header with a value of application/problem+json which reflects the default response body. If the body member indicates a different content type, set the Content-Type header to the appropriate value. For example, in case of an XML body, the value could be application/problem+xml. |
overrideDefaults |
Boolean | ○ | Read-only. Whether you overrode the default error response. |
statusCode |
Integer | ✓ | The status code to return in case of the error. |
ErrorSettings.{errorType}.headers[]: The list of HTTP headers to return in case of the error. By default, API Gateway returns the Content-Type header with a value of application/problem+json which reflects the default response body. If the body member indicates a different content type, set the Content-Type header to the appropriate value. For example, in case of an XML body, the value could be application/problem+xml. |
|||
name |
String | ✓ | The name of the HTTP header to return in case of the error. |
value |
String | ✓ | The value of the HTTP header to return in case of the error. |
ErrorSettings.{errorType} values
This section lists all available error type values that you can enter for the type URL parameter in the Get an error response and Update an error response operations. The ErrorSettings object uses these values as keys indicating different types of customizable errors.
| Value | Description |
|---|---|
API_KEY_FORBIDDEN |
The API key in the request does not have access to the requested resource. |
API_KEY_INVALID |
The API key in the request does not exist. |
JWT_CLAIM_VALUE_INVALID |
The JWT claim value did not pass the JWT validation. |
JWT_SIGNATURE_INVALID |
The JSON web signature in JWT did not pass the JWT validation. |
QUOTA_EXCEEDED |
The quota limit for the API key included in the request has been exceeded during the current time period. |
JwtSettings
Contains 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"
},
{
"name": "scope",
"validate": true,
"required": false,
"value": [
"read",
"write",
"delete"
],
"type": "ARRAY"
}
],
"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 |
|---|---|---|---|
JwtSettings: Contains 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. |
|||
enabled |
Boolean | ✓ | Whether you enabled JWT validation for the endpoint. |
resources |
Jwt |
○ | Contains information about JWT validation settings for each resource associated with an endpoint version. The resources are available through a map of resourceId keys. |
settings |
Jwt |
○ | Contains information about endpoint-level JWT settings. |
JwtSettings.resources: Contains information about JWT validation settings for each resource associated with an endpoint version. The resources are available through a map of resourceId keys. |
|||
{apiResourceId} |
Jwt |
○ | Contains information about JWT settings configured for a resource. |
JwtSettings.resources.{apiResourceId}: Contains information about JWT settings configured for a resource. |
|||
enabled |
Boolean | ✓ | Whether you enabled JWT validation for the resource. |
inherits |
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: Contains 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 |
Jwt |
○ | Contains information about the JWT validation details, such as RSA public keys and JWT claims. |
JwtSettings.settings.validation: Contains information about the JWT validation details, such as RSA public keys and JWT claims. |
|||
claims |
Jwt |
○ | The collection of custom and reserved JWT claims that API Gateway validates in incoming requests. Reserved claims are predefined (as per RFC 7519) and serve as a starting point for your JWT claim configuration. Custom claims refer to both private and public claims and you can define them at will. To prevent claim name collisions, you can register public claims at the IANA JSON Web Token Claims registry or give them collision-resistant names, such as universally unique identifiers (UUIDs) or object identifiers (OIDs). Private claims usually contain information specific to your organization, such as internal user ID. They are different from public claims as they are not registered at the IANA JSON Web Token Claims registry, and should be used with care. |
rsaPublicKeyA |
Jwt |
○ | Contains information about the primary RSA public key that you use for JWT validation. |
rsaPublicKeyB |
Jwt |
○ | Contains information about the backup RSA public key for use during key rotations. |
JwtSettings.settings.validation.claims[]: The collection of custom and reserved JWT claims that API Gateway validates in incoming requests. Reserved claims are predefined (as per RFC 7519) and serve as a starting point for your JWT claim configuration. Custom claims refer to both private and public claims and you can define them at will. To prevent claim name collisions, you can register public claims at the IANA JSON Web Token Claims registry or give them collision-resistant names, such as universally unique identifiers (UUIDs) or object identifiers (OIDs). Private claims usually contain information specific to your organization, such as internal user ID. They are different from public claims as they are not registered at the IANA JSON Web Token Claims registry, and should be used with care. |
|||
name |
String | ○ | The name of the JWT claim. For reserved claims, it can either be 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. For custom claims, you can use all alphanumeric characters and the following characters: [-_]. The value is not case-sensitive for reserved claims and case-sensitive for custom claims. For example, if you enter AUD for a value, the system automatically converts it to aud, but scope and SCOPE represent two different values. |
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, STRING, INTEGER, BOOLEAN, or REGEX if it’s a regular expression. |
validate |
Boolean | ○ | Whether to validate the value of the JWT claim at the edge. |
value |
Array, String, Boolean, Number, Null | ○ | The value of the JWT claim, represented as a string, boolean or number if it’s a single value, or as an array if there is more than one value. If the value is a string, it cannot exceed 200 characters. If the value is an array, it cannot contain more than 100 items. |
JwtSettings.settings.validation.rsaPublicKeyA: Contains 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: Contains 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. |
OauthScopeDefinition
Contains information about an OAuth scope.
Download schema:
oauthScope-schema.json
Sample GET:
{
"name": "Books:Read",
"description": "View your books"
}
OauthScopeDefinition members
| Member | Type | Required | Description |
|---|---|---|---|
OauthScopeDefinition: Contains information about an OAuth scope. |
|||
description |
String | ○ | The description of the scope. |
name |
String | ○ | The name of the scope. |
OauthScopesAssignments
Contains information about OAuth scopes configured for an endpoint. You can configure OAuth scopes if the API Gateway product is in your contract and if you are taking part in the API Gateway 1.1 beta program.
Download schema:
oauthDto-schema.json
Sample GET:
{
"enabled": true,
"resources": {
"100": {
"path": "/calendar",
"methods": {
"GET": {
"scopes": [
"read:calendar"
],
"notes": null
},
"POST": {
"scopes": [
"write:calendar"
],
"notes": null
}
},
"scopes": [
"admin:calendar"
],
"notes": null
},
"101": {
"path": "/mail",
"methods": {
"GET": {
"scopes": [
"read:mail"
],
"notes": null
},
"POST": {
"scopes": [],
"notes": null
},
"PUT": {
"scopes": [],
"notes": null
},
"DELETE": {
"scopes": [],
"notes": null
}
},
"scopes": [],
"notes": null
},
"102": {
"path": "/contacts",
"methods": {
"GET": {
"scopes": [],
"notes": null
},
"PUT": {
"scopes": [],
"notes": null
},
"DELETE": {
"scopes": [],
"notes": null
}
},
"scopes": [
"contacts"
],
"notes": "Core contacts API resource"
}
}
}
OauthScopesAssignments members
| Member | Type | Required | Description |
|---|---|---|---|
OauthScopesAssignments: Contains information about OAuth scopes configured for an endpoint. You can configure OAuth scopes if the API Gateway product is in your contract and if you are taking part in the API Gateway 1.1 beta program. |
|||
enabled |
Boolean | ✓ | Whether you enabled the OAuth scopes assignment for the endpoint. |
resources |
Oauth |
○ | Contains information about OAuth scopes assigned to each resource associated with an endpoint version. The resources are available through a map of resourceId keys. |
OauthScopesAssignments.resources: Contains information about OAuth scopes assigned to each resource associated with an endpoint version. The resources are available through a map of resourceId keys. |
|||
{apiResourceId} |
Oauth |
○ | Contains information about OAuth scopes assigned to a resource. |
OauthScopesAssignments.resources.{apiResourceId}: Contains information about OAuth scopes assigned to a resource. |
|||
methods |
Oauth |
○ | Contains information about OAuth scopes assigned to each method associated with a resource. The methods are available through a map of apiResourceMethod keys. |
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. |
scopes |
Array | ○ | The scopes that define the level of client apps’ access to the resource and its associated methods. |
OauthScopesAssignments.resources.{apiResourceId}.methods: Contains information about OAuth scopes assigned to each method associated with a resource. The methods are available through a map of apiResourceMethod keys. |
|||
{api |
Oauth |
○ | Contains information about OAuth scopes assigned to a method. |
OauthScopesAssignments.resources.{apiResourceId}.methods.{apiResourceMethod}: Contains information about OAuth scopes assigned to a method. |
|||
notes |
String, Null | ○ | Read-only. The description of the method. |
scopes |
Array | ○ | The scopes that define the level of client apps’ access to the method. |
Category
Contains 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 |
|---|---|---|---|
Category: Contains information about an endpoint category. |
|||
api |
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. |
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
Contains 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 |
|---|---|---|---|
AcgPair: Contains information about a pairing of contract and group under which you provision the security and delivery settings for an endpoint. |
|||
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. |
CacheKey
Contains information about the cache key settings configured for an endpoint or resource.
Download schema:
cacheKeyDto-schema.json
CacheKey members
| Member | Type | Required | Description |
|---|---|---|---|
CacheKey: Contains 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. For possible values, see CacheKey.option values. 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. |
CacheKey.option values
This section describes each available cache key customization option.
| Value | Description |
|---|---|
IGNORE |
Exclude only specific query parameters from a cache key. |
IGNORE_ALL |
Exclude all query parameters from a cache key. |
INCLUDE |
Include only specific query parameters as part of a cache key. |
INCLUDE_ALL_ALPHABETIZE_ORDER |
Include all query parameters as part of a cache key and sort them alphabetically. |
INCLUDE_ALL_PRESERVE_ORDER |
Include all query parameters as part of a cache key and keep their default order. |
Duration
Contains information about the maximum duration to keep content in a cache.
Download schema:
durationDto-schema.json
Duration members
| Member | Type | Required | Description |
|---|---|---|---|
Duration: Contains 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. |
ImportFile
Contains information about an API definition file to import.
Download schema:
importFileDto-schema.json
Sample POST request:
{
"importFileFormat": "swagger",
"importFileSource": "BODY_BASE64",
"importFileContent": "ewogICAgInN3YWdnZXIiOiAiMi4wIiwKICAgICJpbmZvIjogewogICAgICAgICJ0aXRsZSI6ICJ3ZWF0aGVyLmdvdiBBUEkgMjAxOC0wNS0xNSAxMTo0MjoxOCIsCiAgICAgICAgImRlc2NyaXB0aW9uIjogIlJhcGlkUmVJbXBvcnRfMjAxOC4wNS4xNC4wNy40OS4zOSIsCiAgICAgICAgInZlcnNpb24iOiAiMS4wLjAiCiAgICB9LAogICAgImhvc3QiOiAid3d3LnBldHN0b3JlLmNvbSIsCiAgICAic2NoZW1lcyI6IFsKICAgICAgICAiaHR0cCIKICAgIF0sCiAgICAiYmFzZVBhdGgiOiAiL3Byb2R1Y3Rpb24iLAogICAgInBhdGhzIjogewogICAgICAgICIvYWxsLzIwMCI6IHsKICAgICAgICAgICAgImdldCI6IHsKICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJMaXN0IEl0ZW0gbnVtYmVycyIsCiAgICAgICAgICAgICAgICAib3BlcmF0aW9uSWQiOiAiaXRlbUdFVCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgR0VUIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0sCiAgICAgICAgICAgICJwb3N0IjogewogICAgICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogIkxpc3QgSXRlbSBudW1iZXJzIiwKICAgICAgICAgICAgICAgICJvcGVyYXRpb25JZCI6ICJpdGVtUG9zdCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgUG9zdCIsCiAgICAgICAgICAgICAgICAgICAgICAgICJzY2hlbWEiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAidHlwZSI6ICJhcnJheSIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAiaXRlbXMiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIiRyZWYiOiAiIy9kZWZpbml0aW9ucy9pbmxpbmVfcmVzcG9uc2VfMjAwIgogICAgICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAgICAgICAicHV0IjogewogICAgICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogIkxpc3QgSXRlbSBudW1iZXJzIiwKICAgICAgICAgICAgICAgICJvcGVyYXRpb25JZCI6ICJpdGVtUG9zdCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgUG9zdCIsCiAgICAgICAgICAgICAgICAgICAgICAgICJzY2hlbWEiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAidHlwZSI6ICJhcnJheSIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAiaXRlbXMiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIiRyZWYiOiAiIy9kZWZpbml0aW9ucy9pbmxpbmVfcmVzcG9uc2VfMjAwIgogICAgICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAgICAgICAicGF0Y2giOiB7CiAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiTGlzdCBJdGVtIG51bWJlcnMiLAogICAgICAgICAgICAgICAgIm9wZXJhdGlvbklkIjogIml0ZW1Qb3N0IiwKICAgICAgICAgICAgICAgICJwcm9kdWNlcyI6IFsKICAgICAgICAgICAgICAgICAgICAiYXBwbGljYXRpb24vanNvbiIKICAgICAgICAgICAgICAgIF0sCiAgICAgICAgICAgICAgICAicmVzcG9uc2VzIjogewogICAgICAgICAgICAgICAgICAgICIyMDAiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJBbiBlbnRpdHkgY29ycmVzcG9uZGluZyB0byB0aGUgcmVxdWVzdGVkIHJlc291cmNlIGlzIHNlbnQgaW4gdGhlIHJlc3BvbnNlIGZvciBQYXRjaCIsCiAgICAgICAgICAgICAgICAgICAgICAgICJzY2hlbWEiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAidHlwZSI6ICJhcnJheSIsCiAgICAgICAgICAgICAgICAgICAgICAgICAgICAiaXRlbXMiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIiRyZWYiOiAiIy9kZWZpbml0aW9ucy9pbmxpbmVfcmVzcG9uc2VfMjAwIgogICAgICAgICAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAgICAgICAiZGVsZXRlIjogewogICAgICAgICAgICAgICAgImRlc2NyaXB0aW9uIjogIkxpc3QgSXRlbSBudW1iZXJzIiwKICAgICAgICAgICAgICAgICJvcGVyYXRpb25JZCI6ICJpdGVtUG9zdCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgRGVsZXRlIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICB9LAogICAgICAgICIvZ2V0LzIwMCI6IHsKICAgICAgICAgICAgImdldCI6IHsKICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJMaXN0IEl0ZW0gbnVtYmVycyIsCiAgICAgICAgICAgICAgICAib3BlcmF0aW9uSWQiOiAiaXRlbUdFVCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgR0VUIGZvciAvZ2V0LzIwMCBwYXRoIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICB9LAogICAgICAgICIvR0VULzIwMCI6IHsKICAgICAgICAgICAgImdldCI6IHsKICAgICAgICAgICAgICAgICJkZXNjcmlwdGlvbiI6ICJMaXN0IEl0ZW0gbnVtYmVycyIsCiAgICAgICAgICAgICAgICAib3BlcmF0aW9uSWQiOiAiaXRlbUdFVCIsCiAgICAgICAgICAgICAgICAicHJvZHVjZXMiOiBbCiAgICAgICAgICAgICAgICAgICAgImFwcGxpY2F0aW9uL2pzb24iCiAgICAgICAgICAgICAgICBdLAogICAgICAgICAgICAgICAgInJlc3BvbnNlcyI6IHsKICAgICAgICAgICAgICAgICAgICAiMjAwIjogewogICAgICAgICAgICAgICAgICAgICAgICAiZGVzY3JpcHRpb24iOiAiQW4gZW50aXR5IGNvcnJlc3BvbmRpbmcgdG8gdGhlIHJlcXVlc3RlZCByZXNvdXJjZSBpcyBzZW50IGluIHRoZSByZXNwb25zZSBmb3IgR0VUIGZvciAvR0VULzIwMCBwYXRoIiwKICAgICAgICAgICAgICAgICAgICAgICAgInNjaGVtYSI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImFycmF5IiwKICAgICAgICAgICAgICAgICAgICAgICAgICAgICJpdGVtcyI6IHsKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAiJHJlZiI6ICIjL2RlZmluaXRpb25zL2lubGluZV9yZXNwb25zZV8yMDAiCiAgICAgICAgICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0KICAgICAgICB9CiAgICB9LAogICAgInNlY3VyaXR5RGVmaW5pdGlvbnMiOiB7CiAgICAgICAgImFwaV9rZXkiOiB7CiAgICAgICAgICAgICJ0eXBlIjogImFwaUtleSIsCiAgICAgICAgICAgICJuYW1lIjogImFwaV9rZXlfYmFzaWMiLAogICAgICAgICAgICAiaW4iOiAicXVlcnkiCiAgICAgICAgfQogICAgfQp9",
"contractId": "1",
"groupId": 1
}
ImportFile members
| Member | Type | Required | Description |
|---|---|---|---|
ImportFile: Contains information about an API definition file to import. |
|||
contractId |
String | ○ | The unique identifier for the contract under which to provision the endpoint. |
groupId |
Number | ○ | The unique identifier for the group under which to provision the endpoint. |
import |
String | ○ | The content of the API definition file encoded in Base64 (see RFC 4648 for details). Specify this only if you set the corresponding importFileSource to BODY_BASE64. |
importFileFormat |
Enumeration | ✓ | The format of the API definition file, either raml or swagger. You cam import RAML 0.8 files and Swagger 2.0 or 3.0 files. |
importFileSource |
Enumeration | ✓ | The location of the API definition file, either URL if you store the file on the web, or BODY_BASE64 if you encode the file contents in the request body. |
importUrl |
String | ○ | The URL from which to retrieve the API definition file. Specify this only if you set the corresponding importFileSource to URL. |
root |
String | ○ | If the import file located at the importUrl is a ZIP archive, this identifies the API definition’s filename within the archive. |
ApiVersionDetails
Contains information about a major API version. This refers to REST API versioning and is a different concept than the endpoint configuration versions you create at Akamai.
Download schema:
apiVersionInfo-schema.json
ApiVersionDetails members
| Member | Type | Required | Description |
|---|---|---|---|
ApiVersionDetails: Contains information about 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 |
Enumeration | ✓ | The location of the API version value in an incoming request. Either HEADER, BASE_PATH, or QUERY parameter. |
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. |
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 Control Center 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: 5/29/2019