Register or update your API by importing an API definition file that describes it.

Before you import

To ensure the smooth import of your API details, consider the following tips on preparing a Swagger or RAML API definition file.

• You can include an array type inside a JSON/XML object.
• To apply formatting to descriptions in a Swagger file, use Markdown instead of HTML. Swagger doesn’t render HTML tags in the output and interprets them as plain text.
• The properties you need for a successful API registration are listed in Bindings with UI fields.
• The maximum size of Swagger file in YAML format is 10 megabytes.

Consider the following when you reimport an API definition file:

• The API name, Access control group, API hostnames, and Categories fields do not change during reimport.
• If you change a Resource path and a resource’s associated methods, this may impact your traffic and cause issues for your API consumers. Ensure that you are aware of possible implications when you change these parameters.
• When multiple APIs are provided in one file, first one is imported.

Supported formats

The API Definition application lets you programmatically define an API endpoint and its set of component resources. You can do it manually, by filling the form or you can import a Swagger or RAML file which will be parsed to API definition.

You can import a Swagger file in the following supported formats, but note that there are differences in the syntax, functionalities, and, in some cases, limitations. This section clarifies how to import API definitions files, which Swagger/RAML fields are supported, what the syntax should look like, and what are constraints.

The following fields are supported.

❗️

Be mindful of the fields' nesting levels; even though some fields share names, they may be at different levels and therefore not be supported. Field naming provided in the following table will be used in next sections.

RAML 0.8

title
baseUri
{resourcePath}
├── description
├── uriParameters
│   └── {parameterName}
│       ├── description
│       ├── type
│       ├── minimum
│       ├── maximum
│       ├── maxLength
│       └── minLength
└── {operation}
    ├── description
    ├── {parameterLocation}
    │   └── {parameterName}
    │       ├── type
    │       ├── description
    │       ├── required
    │       ├── maximum
    │       ├── minimum
    │       ├── maxLength
    │       └── minLength
    └── body
        └── {mediaType}
            └── schema
                ├── {Schema Object}
                └── !include

Swagger 2.0

📘

The in: formData parameter isn't supported. Instead, use in: body for each operation.

swagger
schemes
host
basePath
definitions
parameters
info
├── description
├── title
└── version
securityDefinitions
└── APIKeyHeader
    ├── type
    ├── name
    └── in
paths
└── {resourcePath}
    └── {operation}
        ├── description
        ├── summary
        └── parameters
            ├── name
            ├── in
            ├── description
            ├── required
            ├── type
            ├── maximum
            ├── minimum
            ├── maxLength
            ├── minLength
            ├── schema
            │   ├── {Schema Object}
            │   └── $ref
            └── $ref

Swagger 3.0.x

📘

If the description field is present, then summary value is ignored (applies to all Swagger versions).

openapi
info
├── description
├── title
└── version
servers
└── url 
components
├── securitySchemes
│   └── apiKey
├── schemas
└── parameters
security
└── apiKey
paths
└── {resourcePath}
    ├── description
    ├── summary
    └── {operation}
        ├── description
        ├── summary
        ├── parameters
        │   ├── name
        │   ├── in
        │   ├── description
        │   ├── required
        │   ├── schema
        │   │   ├── type
        │   │   ├── minimum
        │   │   ├── maximum
        │   │   ├── minLength
        │   │   └── maxLength
        │   └── $ref
        └── requestBody
            ├── description
            ├── required
            ├── content
            │   └── {mediaType}
            │       └── schema
            │           ├── {Schema Object}
            │           └── $ref
            └── $ref

Swagger 3.0 limitations

API Definitions supports the import of API definition files in Swagger 3.0 format with the following limitations, which you should review before importing your file.

• API Definitions supports variables in base paths and resource paths, but not in hostnames, what includes schema (for example, http, https). For example, you may include this URL in the servers object: https://my-api.akamai.com/USERNAME, but not this one: https://USERNAME.akamai.com
• API Definitions does not support WebSocket protocols,ws:// and wss:// .
• You can only describe one API key per API configuration.
• API Definitions does not support the not keyword.
• API Definitions does not support the explode and style properties used for parameter descriptions.
• API Definitions does not support the nullable attribute used to specify that a parameter value may be null.

📘

The following limitations are for servers.url:
Supported: http and https schemas, no schema is treated as http.
Not supported: Variable names in {brackets}.

Swagger 3.1.x

openapi
info
├── title
├── version
├── summary
└── description
servers
└── url
webhooks
└── {webhookName}
    └── {pathItem}
components
├── securitySchemes
 │   └── apiKey
├── schemas
├── parameters
└── pathItems
security
└── apiKey
paths
└── {resourcePath}
    ├── description
    ├── summary
    └── {operation}
        ├── description
        ├── summary
        ├── parameters
        │   ├── name
        │   ├── in
        │   ├── description
        │   ├── required
        │   ├── schema
        │   │   ├── type
        │   │   ├── minimum
        │   │   ├── maximum
        │   │   ├── minLength
        │   │   ├── maxLength
        │   │   ├── $ref
        │   └── $ref
        └── requestBody
            ├── description
            ├── required
            ├── content
            │   └── {mediaType}
            │       └── schema
            │           ├── $ref
            └── $ref

Swagger 3.1 limitations

API Definitions supports the import of API definition files in Swagger 3.1 format with the following limitations, which you should review before importing your file.

Server URLs and variables

• Variables in server URLs are expanded before import. If a variable defines enum values, each value produces a separate hostname entry. If only default is defined, it is used as the value. Variables without either enum or default cause the server entry to be dropped with a warning.
• API Definitions does not support server objects defined at the path or operation level, only top-level servers.
• WebSocket schemes ws:// and wss:// trigger a warning and the scheme is not set

Paths and resources

• References from paths to #/components/pathItems/<name> are supported only as a flat, direct reference to an existing named Path Item. References to non-existent names, references that point inside a Path Item (like #/components/pathItems/Item/get), or references to other locations result in a warning and the path is skipped.
• Webhooks are not imported.
• The TRACE method is not supported.
• The following OpenAPI 3.1 JSON Schema 2020-12 keywords are not supported and trigger a warning: const, prefixItems, contains, minContains, maxContains, if/then/else, dependentSchemas, dependentRequired, propertyNames, patternProperties, unevaluatedProperties, unevaluatedItems, contentMediaType, contentEncoding, contentSchema, $id, $anchor, $dynamicAnchor, $vocabulary, $comment.
• Boolean schemas , liketrue or false used in place of a schema object, are not supported and trigger a warning.
• The nullable keyword was removed in OpenAPI 3.1. Use type: ["<type>", "null"] instead. A two-element type array containing exactly one non-null type and "null" is imported as nullable. Type arrays with more than one non-null type, like ["string", "number"] are not supported and trigger a warning.
• The following schema keywords are not supported (as in OpenAPI 3.0): not, format, pattern, uniqueItems, minProperties, maxProperties, readOnly, writeOnly, multipleOf.
• allOf, anyOf, and oneOf are partially supported. allOf branches are merged into a single object. For anyOf and oneOf, only the first branch is imported. A warning is issued in all cases. Exception: an anyOf or oneOf with exactly two branches where one branch is {type: "null"} is treated as a nullable shorthand and imported without a warning.

Security

• Only apiKey security scheme type is supported. Schemes of type http, oauth2, openIdConnect, and the new mutualTLS type trigger a warning and are not imported.

• You can only describe one API key per API definition.

• API Definitions does not support security requirements defined at the operation level. The top-level security definition applies to all operations.

Parameters

API Definitions does not support:

• the explode and style properties used for parameter descriptions.

• the content alternative representation inside a Parameter or Header Object. Use schema to define parameter type and constraints.

• path-level parameters defined on the Path Item Object

Other

• API Definitions does not support externalDocs.

• tags on operations are silently ignored.

• Response body headers support only simple types (string, integer, number, boolean). Complex types in response headers trigger a warning and are not imported.

Schema Object

schema
├── type
├── required
├── maximum
├── minimum
├── maxLength
├── minLength
├── maxItems
├── minItems
├── items
└── properties

Binding with UI fields

API endpoint details

API key parameter-location property example:

API resource details

Parameters with location in header, cookie or query string

📘

If parameter type is array, then elements: Min, Max, Required and Type are imported from object specified inside the array.

Parameters with location in request body

📘

You can only refer to one media type (for example, application/json) in a request body definition.
In case you have multiple media types, only the first one is imported.
Note, that when xml and JSON have identical schemas, we support xml and JSON 2 media types.

Allowed parameter types

Import API details

You can populate most of the API endpoint and resource information automatically by importing an API definition file in an Swagger or RAML format. If you want, you can edit the imported values before saving your API configuration. You can use the import feature either when registering an entirely new API, or when editing details about an existing inactive API.

For general information on how to create your API definition file, see one of the following specifications:

• RAML 0.8
• Swagger 2.0
• Swagger 3.0 supported with limitations
• Swagger 3.1 supported with limitations

1. Go to ☰ > CDN > API definitions.

2. On the API Definitions page, click Register an API.

3. On the Register new API page, click Import API definition.

4. In the Import API window, select the Import file format of your API definition file.

5. In the Import API from area, import file stored on the web or a local file:

   • To fetch and import a file stored on the web, select URL and enter the address in the URL field.

   • To import a local file, select File, click Choose file, and go to the file that you want to upload.

   📘

   You can upload a ZIP file that contains your API definitions with dependent files.

6. Optional: If you uploaded a ZIP file, in the Root file name field, enter the name of the base file that all other API definition files in your zip archive refer to.

7. Click Import.
   The import may take a few minutes. Once it’s complete, the data from your API definition file appears in the fields on the Register new API page.

   If the system encounters any issues during import, a yellow banner appears at the top of the page with all issues listed. To learn how to troubleshoot the most common import-related error messages, see API definition import error troubleshooting.

8. From the Access control group menu, select the access control group that you want to associate with the API.

   An access control group (ACG) is a group of users who can view or edit an API. You can select only the ACGs for which you have a role with at least the API Definitions URL Path Editor permission in the Identity and Access Management app. The ACG selection impacts the hostname selection during API registration. Each ACG has a set of hostnames tied to it via a property configuration. Consider that for example the endpoints created within a certain ACG are only available to use in Key collections and Throttling counters created within the same or parent ACG. See the Identity and Access Management Online Help to learn more about assigning permissions.

🚧

Ensure that the ACG you select here matches the one in the security configuration where you’ll be referencing this registered API. Otherwise, you won’t be able to set up protections for this API.

9. If your API uses GraphQL to describe content and deliver it to clients in a structured form, set the GraphQL API switch to Yes.
   This will enable you to configure GraphQL query and body parameters and set GraphQL-specific caching instructions if API Gateway is in your contract. Learn more about GraphQL.

10. If your API uses API keys for authentication:

    a. In the API key location area, select the location for your API key.

    b. In the Name field, enter a name for the API key location.
    where location is either Header, Cookie, or Query parameter.

    ​Akamai​ uses API keys for user quota, traffic limit & throttling, reports, and privacy and access control.

    If you decide to use API keys for your API configuration, to make productive use of the security benefits that the keys provide, your API consumers should make only secure (HTTPS) requests to your API.

    API key authentication is one of the two API Gateway protection methods independent of web application firewall solutions. If you’re an API Gateway customer, you can also use JSON web tokens to improve security. To optimize the performance of your system, it’s best to implement one API Gateway protection method per API configuration. Learn more about JWT validation.

11. In the Description field, enter a description for your API.

12. In the Categories field, enter or select categories to serve as filters on the main API Definitions page.

13. If your API will only contain Bot Manager Premier resources, turn the Case-sensitive URLs and parameters switch off.
    If this switch is off, Akamai disregards the case of the following elements in incoming requests: base path, resource path, parameter name, parameter value.

    If an API is case-sensitive and a bot operator changes a path’s or parameter’s case in a request, the API doesn’t match the request format and bot detections don’t apply. This may open an evasion path. Disabling the case-sensitivity helps you avoid these potential bot evasions.

14. If your API uses versioning, follow Enter API version details.

API definition import error troubleshooting

The following table lists the common error messages that you may encounter after importing an API definition file in API Gateway. Each error message has a corresponding description and a suggested solution.