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 allows to 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. Initially, only Swagger version 2.0 was supported, but later Swagger version 3.0.x file support was added.
You can import a Swagger file in 3.0.x, but note that there are differences in the syntax, new functionalities iand some 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

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 description field is present, then summary value is ignored (applies to both 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

📘

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

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, but with a list of 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.

Swagger 3.0 limitations

API Definitions supports the import of API definition files in Swagger 3.0 format with the limitations listed below. Review these limitations before importing your API definition 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.