Editing an API definition

Use this topic to specify configuration settings for an API. You can do this when you create the initial definition, or you can do it later by editing an existing definition.

1. Access the API Setup page in one of the following ways:
   • During the initial creation of an API, the API wizard guides you to enter the minimum configuration settings, and then provides an Edit API icon. When you select that icon, the API Setup page is displayed. Proceed to the next step.
   • When you want to edit an existing API, you can access the API settings by going to the navigation pane and clicking Develop. Select the API that you want to edit. The API Setup page is displayed.
2. In the API Setup tab, you can edit the following sections:
   1. Optional: In the Info section, edit any or all of Title, Description, and Version.
      Note: If you change the Title or Version, when you save the API definition a new API definition is created, copying the current configuration.
   2. Optional: 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 Defining Paths for a REST API.
   3. Optional: 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 Defining Paths for a REST API.
   4. Optional: If you want external developers on the portal to access your APIs by using a host address that is not the same as the API endpoints that are defined for the gateway services where your API will run, use the Address field in the Host section to define the host name that is to be used.
      Note: To enable this capability, you must additionally configure API vanity endpoints in the Catalog Settings for the Catalog to which the API is published. For information on configuring vanity endpoints, see Creating and configuring Catalogs
   5. Optional: In the Base Path section, you can change the path segment that is shared by all operations in your API.
      The base path is the initial URL segment of the API, and does not include the host name or any additional segments for paths or operations.
   6. In the Schemes section, select which transfer protocols you want your API to use. HTTPS is selected by default.
      Note: If your API is enforced by an API Connect gateway, only the HTTPS protocol is supported. See the following Lifecycle section for instructions about how to enable enforcement.
   7. In the Lifecycle section you can use the drop-down menu to change the phase of the lifecycle that your API is in.
      • Realized (default) - The API is in the implementation phase.
      • 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.

      You can also edit the following options:

      • Enforced - Select this option to enforce the API by using the API Connect Gateway. Clear this option if you are managing the API on a gateway other than an API Connect gateway. Although not published to a gateway by API Connect, an unenforced API is still available in the Developer Portal for subscription by application developers.
      • Testable - Select this option to allow the API's 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 Catalog.
      • CORS - Select this option to enable cross-origin resource sharing (CORS) access control for your API.
      • Application authentication - Select this option to protect your API with a certificate, for example, by using TLS mutual authentication.

        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.

        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.

      • Buffering - if you select this option, the API requests and responses are first buffered before being processed on the DataPower® API Gateway. If you clear this option, the gateway streams the API requests and responses byte by byte where possible. However, situations in which the gateway will buffer the requests and responses even if the Buffering option is cleared include the following:
        • The API policy assembly includes a parse policy; the parse policy buffers the message before reading it into the parse tree.
        • The API policy assembly includes policies that use GatewayScript functions that require the message to be buffered; for example, context.message.body.readAsBuffer, context.message.body.readAsJSON, context.message.body.readAsXML.
        • The API policy assembly includes policies that use the apim.getvariable GatewayScript function, which is backwardly compatible with the DataPower Gateway (v5 compatible); the gateway falls back to using buffering mode.
        • The Content-Type header of the incoming request is application/x-www-form-urlencoded; the gateway reads the message to populate the form parameters.
        • A WSDL API routes the request based on the name of the root element inside the SOAP body.
        • The API policy assembly includes a map policy; the gateway buffers the message before executing this policy.
   8. Optional: In the Parameters section, add parameters that you want to be defined on all the Paths in the API; these parameters are inherited by all the Path definitions in the API. Click Add and complete the following fields:
      • Name - Provide a name for your parameter.
      • Located In - Select where the parameter is found in the call of your operation.
      • 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 in the Definitions section. For more information about creating JSON schemas, see step 6.
      • Description - Provide a description of your parameter.
      • Required - Select this check box to specify that the parameter is required for a call to be valid.
   9. Optional: In the Tags and External Documentation section, click Add to provide any tags and external documentation details that you want to refer users to. Tags added in this way appear in the OpenAPI definition of the API, but are not used by API Connect for any indexing.
   10. Click Save to save your updates.
3. In the Security Definitions tab, you can specify the security definitions that might be used by the API or its operations. A security definition specifies all the settings for a particular aspect of API security; for example, the user registry that you use to authenticate access to the API. For more information, see Configuring API security.
4. In the Security tab, select the security definitions that you want to apply to your API. Click Add to make your definitions appear in the list of security definitions. Click Save to save your updates.
   To be available in the Security section, definitions must have been defined in the Security Definitions section.
5. In the Paths tab, you can add API Paths to your definition.
   A Path is a unit of a REST API that can be called by applications. A Path comprises of one or more HTTP verb operations and a URL path that, when exposed, is combined with the base path of the API. By configuring the Path, you define how the API is exposed to your developers. For more information about Paths, operations, and adding tags to your operations, see Defining Paths for a REST API and Configuring an operation.
6. In the Definitions tab, you can create schema definitions.
   These definitions can then be referenced in an operation to provide developers with information about the request they should make, or the 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 - DataPower Gateway (v5 compatible) policy is used.
   1. Click Add.
      The Edit Definitions page is displayed.
   2. Complete the Name field for your definition.
   3. From the Type drop-down list, select the type of your definition.
   4. Optional: In the Description field for your definition, provide a description of what is defined by the definition.
   5. 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, select the Additional properties check box.
   6. Click Save to complete the details of your definition's properties. Each property requires a name and type, and can also have an example and description.
   7. Optional: You can add additional properties by clicking Add again.
   Note:

   • You can include more complex schema definitions in your API by using the Source view, and editing your API OpenAPI definition directly. For more information, see the OpenAPI specification.
   • If, for a schema definition property of type long, you specify a minimum or maximum parameter in the OpenAPI source, the highest value you can set is 9007199254740992; if you exceed this value then, due to rounding behavior, an incorrect value might be saved.

   Tip: You can click Edit schema in a definition to display the Add XML schema window. In this window, you can edit, upload, or infer an XML schema from a JSON schema.
7. In the Properties tab, you can define any API properties that you want to use. For more information, see API properties.
8. In the Target Services tab, add any web services that you want to use in your API definition. Complete the following steps:
   1. Click Add.
   2. To upload the service information from a stand-alone .wsdl file, or a .zip file that contains a WSDL file and its dependent documents, you can either drag and drop your file, or browse and select the file that you want to use. After you upload the file, the WSDL is evaluated and a message displays whether the WSDL is valid.

      If you upload a .zip file, you can include in the .zip file an options file to specify additional directives. For details, see Using an options file when importing a WSDL service.

   3. In the Select Target Service pane, select the service that you want to add, then click Submit.

   The target services that you add are now available in the palette on the Assemble view for you to add to your API assembly flow; for more information, see Including components in your assembly.

9. In the Categories tab, define any categories that you want to organize your APIs into. Click Save to save any updates.
   By organizing your APIs into categories, you can provide a hierarchical display for your APIs in the Developer Portal. For more information, see Organizing your APIs and Products into categories.
10. If the gateway type associated with the API is the DataPower API Gateway, select the Activity Log tab to configure your logging preferences for the API activity that is stored in API Connect Analytics. By default, the content type that is collected and stored in API event records is activity for when API execution completes successfully, and payload for when API execution completes with an error code. For more information, see Activity logging with the DataPower API Gateway. Click Save to save any updates.

    Note that if the gateway type associated with the API is the DataPower Gateway (v5 compatible), you can configure your logging preferences by applying an Activity Log policy in the Assemble view. For more information, see Activity Log.

    The gateway type that is associated with the API by default when you first create it depends on the gateway services that are defined in the Sandbox Catalog. For more information, see API Connect gateway types and Specifying the gateway type for an API definition.

11. Select the Assemble view to configure and test the policy assembly for your API. Click Save to save any updates.
    You can drag and drop policies and logic constructs onto the assembly canvas, and use the internal test tool to test your assembly. For more information, see The Assemble view, and API policies and logic constructs.