Creating a new REST OpenAPI definition

You can create and edit draft REST API definitions by using the API Designer or the API Designer user interface in IBM® API Connect.

About this task

You can complete this task either by using the API Designer UI application, or by using the browser-based API Manager UI.

API Manager UI only: To complete this task you must be assigned a role that has the Api-Drafts:Edit permission. The pre-supplied Developer role has this permission by default; if you are assigned a custom role it must have this permission. For more information, see Creating custom roles.


To create a new REST OpenAPI definition, complete the following steps.

  1. In the navigation pane, click Develop icon in the API UI navigation pane Develop, select the APIs tab, then click Add > API (from REST, GraphQL or SOAP).
    The Select API type screen is displayed.
  2. Select OpenAPI 2.0 or OpenAPI 3.0 according to which version of the OpenAPI specification your API is to be based on.
  3. Select New OpenAPI .
  4. Click Next. Specify the API summary in the Info section. You can fine-tune the API after it is created.
    • The Title can include special characters but should be kept short so that it can be easily displayed in the user interface.
    • The Name is entered automatically. The value in the Name field is a single string that is used to identify the API in developer toolkit CLI commands. To view the CLI commands to manage draft APIs, see apic draft-apis.
    • The Version corresponds to the value of the info.version property of the API's OpenAPI definition. The version.release.modification version numbering scheme is recommended; for example 1.0.0.
    • The Base path is the URL segment of the API and does not include the host name or any additional segments for paths or operations. The base path cannot include special characters and must begin with a / character even if it is otherwise empty.
    • The optional Description helps to identify the API.
  5. Click Next. In the Secure section, configure the API security that you require.
    • Secure using Client ID - Select this option to require an Application to provide a Client ID (API Key). This causes the X-IBM-Client-Id parameter to be included in the request header for the API. If selected, you can then select whether to limit the API calls on a per key (per Client ID) basis:
      • Limit API calls on a per key basis - If selected, you must configure the rate limit that you require. Rate limits control the maximum number of calls allowed within a time period (hour, minute, month or day). For example, 100 calls per hour.
      For information about security options in IBM API Connect, see Configuring API security.
    • CORS - Select this option to enable cross-origin resource sharing (CORS) support for your API. This allows your API to be accessed from another domain.
      • CORS support is available only on the DataPower® API Gateway.
      • When CORS is enabled, the API Gateway runs the cors preflow policy to handle all CORS requests that are made to the API.
      • When CORS is enabled and a preflight request is received, only the following API actions are performed:
        • The cors preflow policy configures the appropriate response headers.
        • The response headers are set.
      • When a preflight request is received, the request.attributes.isCORSPreflight flag is set to true.
      • For all preflight requests, the security and client-identification preflow policies are always skipped, whether CORS is enabled or not enabled.
  6. Click Next to create your API definition.

    The Summary panel displays messages as the definition is created, and the selected security options and rate limits are enforced.

  7. Select one of the following options:
    • To further configure your API, click Edit API. For details, see Editing an API definition.
    • If you do not want to configure your API further at this time, click the Develop link in the breadcrumb trail to return to the welcome page; you can then move on immediately to another task. For details on how to configure your API later, see Editing an API definition.


You successfully created a REST API definition. For API Designer, the specifications for the APIs and Products are stored in the directory that you specified when you logged in. For API Manager, the specifications for the APIs and Products are stored on the management server.

What to do next

APIs are made available to application developers by including them in a Product, and then publishing that Product to a Catalog. For more information, see Working with Products and Working with Catalogs.