Import API definition file

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.
  • There are no nesting depth restrictions for JSON elements, but the API Gateway user interface only displays up to three nesting levels.
  • 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 Supported API definition elements.

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.

Supported API definition elements

Review the elements that you can include in your Swagger or RAML API definition import file.

API endpoint details
See the API endpoint details that you can include in your API definition import file, their corresponding Swagger and RAML properties, and a sample value for each entry.

API element

Swagger property

RAML property

Example

API name

title

title

Sample API

Hostname

host

baseUri

http://myapi.example.com

Base path

basePath

A top-level resource.

/myapi123

API key name and location

securitySchemes

securitySchemes

{```
      ```
"type":"apiKey",```
    ```"name":"api_key",```
    ```"in":"header"```

}

API description

description

description

This is a sample API.

API resource details
See what API resource details you can include in your API definition import file, their corresponding Swagger and RAML properties, and a sample value for each entry. In Swagger files, resources are included in the Paths object. In RAML, they are nested under the top-level resource property.

API element

Swagger property

RAML property

Example

Resource name

A top-level property in the Paths object.

A resource nested in the top-level resource.

/cpcode

Resource path

A top-level property in the Paths object.

A resource nested in the top-level resource.

/cpcode

Resource method

A seccond-level property in the Paths object.

A top-level property in a resource.

post

Resource notes

description

description

This is a sample resource.

Parameter details
Review the parameter details that you can include in your API definition import file, their corresponding Swagger and RAML properties, and a sample value for each entry. In Swagger files, parameters are included in the Parameters object. In RAML, depending on the parameter type, they are nested either under the queryParameters or uriParameters property.

API element

Swagger property

RAML property

Example

Parameter name

name

A top-level property in either queryParameters or uriParameters property object.

status

Parameter location

in

Indicated by queryParameters or uriParameters.

query

Parameter type

type

type

integer

Required parameter

required

required

true

Parameter data types

Data type

Optional attributes

String

minLength and maxLength

Integer

minimum and maximum

Number

minimum and maximum

Boolean

N/A

JSON/XML object

N/A

Swagger 3.0 support

You can import of API definition files in OpenAPI 3.0 (Swagger 3.0) format, but with the limitations listed in OpenAPI 3.0.x support.

Import API details

You can populate most of the API endpoint and resource information automatically by importing an API definition file in an OpenAPI (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:

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

  1. 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.

  2. 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 and reports.

    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.

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

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

  5. 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.

  6. 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.

Error

Description

Solution

The <property> property at <pointer> pointer is not supported.

API Gateway does not support the property in your API definition file.

The message is informational and no action is required. The property has not been imported, but other supported properties have been successfully reflected in the API definition.

Swagger/RAML version is not supported.

API Gateway does not support the version of your Swagger or RAML API definition file. The currently supported versions are Swagger 2.0, Swagger 3.0, and RAML 0.8.

Ensure that the version of your API definition file is either Swagger 2.0, Swagger 3.0, or RAML 0.8.

Invalid schema

Your imported API definition is not a valid Swagger 2.0, Swagger 3.0, or RAML 0.8 file.

Depending on your API definition file format, compare the file with either Swagger 2.0 schema, Swagger 3.0 schema, or RAML 0.8 specification. Resolve the validation errors and reimport the API definition.

Invalid syntax

This error can indicate two different issues:

  • At least one file in your imported API definition has an incorrect format. The supported file formats are json and yaml.
  • Your API definition file does not specify the Swagger or RAML version it represents.

Ensure that your files have correct formats and that they specify the Swagger or RAML version.

Unable to load ref: <ref>

This error can indicate two different issues:

  • The URL you entered in the Import API window does not point to a valid API definition file.
  • When you’re importing a ZIP file, the specified Root file name does not correspond to any file in your API definition.

Ensure that the URL you entered points to a valid API definition file and, in case of a ZIP file upload, the Root file name points to the appropriate root file.

Parameters with multiple type not supported

API Gateway only supports parameter definitions that specify a single type of a parameter.

Find the multi-type parameters in your schema files, for example, by searching by the following phrase: "type": [ and change them to single-type. Reimport the API definition file.


Did this page help you?