Composing a REST API definition

You can create and edit draft REST API definitions by using the API Designer or API Manager user interfaces.

To compose a REST API definition, complete the following steps:

1. Click APIs.
   The APIs tab opens.
2. If you have not previously pinned the UI navigation pane then click the Navigate to icon .
   The API Manager UI navigation pane opens. To pin the UI navigation pane, click the Pin menu icon .
3. Click Drafts in the UI navigation pane, and then click APIs.
   The APIs tab opens.
4. Click Add > New API.
   Click Add and then click New OpenAPI from scratch.
   Click Add and then click API from the Compose section.
5. Specify basic information about the API.
   • The title can include special characters but should be kept short so that it can be easily displayed in the user interface.
   • The name should be kept short and can contain only lowercase alphanumeric characters (a-z and 0-9), underscore characters (_), or hyphen characters (-). A hyphen cannot be used as the first or last character in the name.
   • 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 version corresponds to the value of the info.version property of the API's OpenAPI (Swagger 2.0) definition. The version.release.modification version numbering scheme is recommended; for example 1.0.0.
6. Expand Additional properties to specify additional properties for the API.
   1. From the API template field, select Default if you want to use the template defined as the default, to create the API definition. This can either be the built-in default .hbs template file, or another template file that you have configured as the default by using configuration variables. You can also select OAuth2 Provider to use the template for an OAuth 2.0 API definition, or select a custom template that you created.
      Note:

      • Any templates that you have configured for use in the developer toolkit command line interface, including any configured default, are available for selection from this field.
      • Only the built-in templates, which are provided with API Manager, are available for selection. Custom templates are not displayed.

      For information about template files and configuration variables, see Creating and using API and Product definitions templates and Toolkit command summary.
   2. Specify a target endpoint if known.
   3. Define the security scheme that an application must use to identify itself when calling the API operations. Select None, Client ID, or Client ID and secret. (Securing an API with a client ID and client secret is similar to requiring a user ID and password.)
   4. Select the Enable CORS check box to enable cross-origin resource sharing (CORS) support for your API. If you clear this check box, you can enable CORS support later, as described in Enabling CORS support for an API.
   5. Select Micro and DataPower Gateways, Micro Gateway, or DataPower Gateway as the Gateway server.
7. Specify whether your API should be included in a Product, and then create the API definition.
   1. Select one of the following options:
      • To create your API without adding it to a Product, ensure that Don't add to a product is selected.
      • To create a new Product and include your API in that Product, select Add to a new product and provide a name for your Product.
      • To add your API to an existing Product, select Add to an existing product and then select the Product to which you want to add your API.
   2. Click Add.
      The Design tab for the draft of your API definition opens. You can skip to different sections of your API definition by using the page navigation in the side bar. You can view the OpenAPI (Swagger 2.0) definition of your API in the Source tab and, after you have created an assembly, view your policy assembly in the Assemble tab.
8. Specify whether your API should be included in a Product, and then create the API definition.
   • To create a new Product and include your API in that Product, complete the following steps:
     1. Click Add a product.
     2. In the Product template field, select Default if you want to use the template defined as the default, to create the Product definition. This can either be the default .hbs template file provided with the developer toolkit, or another template file that you have configured as the default by using configuration variables. You can also select a custom template that you created. For information about template files and configuration variables, see Creating and using API and Product definitions templates and Toolkit command summary.
     3. Accept the default values for the Product title, name, and version, or change them as required.
     4. To publish the Product to a target Catalog, ensure that the Publish this product to a catalog check box is selected. You can clear this check box and stage or publish the Product later by using the API Designer UI and API Manager UI, as described in Staging a Product and Publishing a Product.
     5. Select the Catalog that you want to use.
     6. If Spaces have been enabled, select the Catalog and Space that you require.Your Product is staged to the Space that you selected.
     7. Click Create API.
   • To create your API without adding it to a Product, click Create API.
     Tip: You can add the API to one or more Products later, as described in Adding an API definition to existing Products.
   The Design tab for the draft of your API definition opens. You can skip to different sections of your API definition by using the page navigation in the side bar. You can view the OpenAPI (Swagger 2.0) definition of your API in the Source tab and, after you have created an assembly, view your policy assembly in the Assemble tab.
9. In the Design tab, edit the Info section.
   1. Optional: Edit any or all of Title, Name, Version, and Description.
   2. Optional: In the Contact section, provide details for any or all of Name, Email, and URL.
   3. In the Terms and License section, provide details for any or all of Terms of Service, License Name, and License URL.
   4. In the External Documentation section, provide a Description for any external documentation you want to refer users to and a URL for where the documentation can be accessed.
10. In the Schemes section, select which transfer protocols you want your API to use.
    Note:

    • If your API is enforced by an IBM API Connect gateway, only the HTTPS protocol is supported. See Step 15.c for instructions of how to enable enforcement.
    • If you are using a Micro Gateway, you cannot have both an API that uses HTTP and an API that uses HTTPS. Doing so returns the following error when starting the Micro Gateway:

      test-gw did not return a port in timeout.
      Error: Service test-gw started but did not initialize within the timeout period. Dumping log buffer.
      undefined

11. Optional: If your API is to be reached by using a host name that is not your gateway cluster, use the Host field in the Host section to define the host name that is to be used. This does not affect the API's implementation, but will affect test tools and the OpenAPI (Swagger 2.0) definition that is made available to developers.
12. In the Base Path section, you can change the path segment that is shared by all operations in your API.
13. In the Consumes section, select which types of media your API will accept when calls are made to it. In addition to JSON and XML, which are supported by API Connect, you can add other media types by using the Add Media Type field.
    Note: The configurations that you make become defaults for all of the operations in the API. However, you can override these media types for individual operations. For more information, see Creating Paths.
14. In the Produces section, select which types of media your API will return when calls are made to it. In addition to JSON and XML, which are supported by API Connect, you can add other media types by using the Add Media Type field.
    Note: The configurations that you make become defaults for all of the operations in the API. However, you can override these media types for individual operations. For more information, see Creating Paths.
15. Configure the Lifecycle section.
    1. Optional: For Phase, use the drop-down menu to change the phase of the life-cycle that your API is in.
       The options are as follows:

       Identified

       The API is in the early conceptual phase and is neither fully designed nor implemented.

       Specified

       The API has been fully designed and passed an internal milestone but has not yet been implemented.

       Realized

       The API is in the implementation phase.

    2. Optional: Set the Testable toggle to the On position to allow the APIs operations to be tested using the test tool in the Developer Portal.
       Note: For the test tool to work, an API must be included in a Plan in a Product that is staged in a development Catalog.
    3. Set the Enforced toggle to the On position to enforce the API by using the IBM API Connect Gateway.
    4. Set the CORS toggle to the On position to enable CORS access control.
    5. To protect your API with a certificate, by using TLS mutual authentication for example, select Authenticate application.

       When the API is called, an X509 client certificate must be supplied, either in the X-Client-Certificate HTTP header, or as a TLS client certificate from TLS mutual authentication. For any Developer Portal application that calls the API, the certificate must be entered in the Developer Portal user interface; for details, see Registering an application.

       The Gateway service to which the API is published can be configured to use TLS mutual authentication to secure API calls made to that Gateway service; for details, see Configuring the initial Gateway service or Adding more Gateway services.

       If you are using a load balancer, you must configure the load balancer to use the X-Client-Certificate HTTP header to relay the appropriate client certificate to the Gateway service after the load balancer terminates the TLS communication.

       Important: The capability to protect an individual API with TLS mutual authentication was introduced in the IBM API Connect V5.0.8.1 release. If you enable the Authenticate application option for an API, the API will fail validation if imported into in a previous release. If you want to re-use the API in a previous release, remove the following lines from the source YAML for the API:

       application-authentication:
         certificate: true

16. In the Policy Assembly section, click Create assembly to create a policy assembly for your API.
    The assemble view opens and displays a blank assembly on the canvas. For more information about the assemble view, see The assemble view.
17. In the Security Definitions section of the design view, manage any security definitions that might be used by the API or its operations. For more information, see Configuring API security
18. In the Security section, select any security definitions that you want to apply to your API. To be available in the Security section, definitions must have been defined in the Security Definitions section.
19. In the Extensions section, add any vendor extensions you want to use with your API. For more information see, Adding an extension schema to a REST API definition.
20. In the Properties section, define any API properties that you want to use. For more information, see API properties.
21. In the Analytics section, add fields to specify your datatypes.
    For convenience, the header and body types of parameter entries that are listed in the Parameters section are available as items in the drop-down list. You can also add fields to the table that are not already specified in the Parameters section.
    1. Click Add Field + to create a field.
    2. Optional: If you are selecting an existing header or body parameter, select one of the listed Parameters.
    3. Optional: If you are creating a field from the beginning, select Add new field.
    4. Verify or modify the following information in the table for the new field:

       Name

       Names the field that you refer to in your visualization.

       Located in

       Identifies where the field is located in the call. The supported options are payload and header.

       Note: If you specify a payload type, the data must be in a JSON Object. Data that is in a JSON Array or other datatype is not recognized. The field can be nested, but cannot be nested in an array. For example, to map the value of field_3, you can enter field_3 as shown in the following example:

       {"field_1":{"field_2":{"field_3": 123}}}

       ES type

       Specifies the type of search method that can be used for Elasticsearch. The options are keyword, text, long, integer, short, double, float, and geo-point.

       From

       Identifies what type of call the field is found in. Options are request and response.

22. In the Parameters section, add parameters that are shared by all Paths and operations in the API.
    1. Click the Add Parameter icon .
    2. In the Name field, provide a name for your parameter.
    3. In the Located In field, select where the parameter is found in the call of your operation.
    4. Optional: In the Description field, provide a description of your parameter.
    5. Use the Required check box to specify whether the parameter is required for a call to be valid.
    6. Optional: From the drop-down list for Type, select the type of data that the parameter is expected to have when the call is received by API Connect. If you have set Located In to Body then you can select a JSON schema that you have defined for your API. For more information about creating JSON schemas, see step 24.
23. Add paths to your API. For more information, see Creating Paths.
24. In the Definitions section, create JSON schema definitions.
    You reference these definitions in an operation to provide developers with information about the JSON request they should make or the JSON response they should expect to receive from the operation. Your schema definitions are made available to developers through the Developer Portal but are not enforced in any calls to the API unless a Validate (validate) policy is used.
    1. Click the Add Definition icon .
       A new definition is created.
    2. Click the newly created definition to expand its details.
    3. Complete the Name field for your definition.
    4. From the Type drop-down list, select the type of your definition.
    5. Optional: In the Description field for your definition, provide a description of what is defined by the definition.
    6. Complete the details of your definition's properties. Each property requires a name and type and can also have a description.
    7. Optional: To specify that a property is required when the operation is called, select it using the check box in the Required column.
    8. Optional: You can add additional properties by clicking Add Property.
    9. Optional: You can delete properties or definitions by clicking the Delete icon next to the property or definition.
    10. If you want to allow the inclusion of properties that are not included in the definition, so that validation will not fail when a validate-rest policy is used on the request, set Allow additional properties to the On position.
    Note:

    • You can include more complex schema definitions in your API by using the Source tab and editing your API's OpenAPI (Swagger 2.0) definition directly. For more information, see the OpenAPI (Swagger 2.0) specification.
    • Due to a change in the OpenAPI (Swagger 2.0) specification, references to object definitions created before the application of any fixpacks to IBM API Connect Version 5.0 fail validation upon staging. To rectify this, use the Code view to edit the OpenAPI (Swagger 2.0) definition. Where the object definition is referenced, delete the line type: Definition_Name where Definition_Name is the name of the referenced object definition.
    • If, for a schema definition property of type long, you specify a minimum or maximum parameter in the OpenAPI (Swagger 2.0) source, the highest value you can set is 9007199254740992; if you exceed this value then, due to JavaScript rounding errors, an incorrect value might be saved.

    Tip: You can click the Edit inline schema icon next to a definition to display the Provide a schema window. In this window, you can create a schema definition in YAML format or in JSON format by editing the source in the Schema as YAML or Schema as JSON tabs. You can also generate a schema definition from a sample JSON or XML response, by using the Generate from sample JSON or Generate from sample XML tabs. When you want to generate a schema definition from a sample, enter the sample response into the appropriate generate tab, and click Generate to create the schema definition.
25. In the Services section, add any web services that you want to use in your API definition. For more information, see Adding an existing web service to your API definition.
26. To add any tags, in the Tags section click the Add Tag icon . Tags added in this way appear in the OpenAPI (Swagger 2.0) definition of the API but are not used by API Connect for any indexing.
27. Click the Save icon to save your changes.