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:

How to

  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, do one of the following:
    • 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.
      Note: 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.
    Important: 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:
    1. In the API key location area, select the location for your API key.
    2. In the <location> 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 KSD. 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.