Introduction

IBM App Connect provides the ability to expose an integration flow as a REST API. This API can be represented and managed in IBM API Connect.

For users who have an App Connect free, personal or professional subscription (obtained via IBM Marketplace or IBM sales) then the definition of the API can be downloaded in the OpenAPI 2.0 (swagger 2.0) format, which is a specification for describing RESTful APIs that can then be interpreted by either humans or computers. As a result the API can be imported into and consumed by IBM API Connect.

For users on IBM Cloud (formerly Bluemix) the steps are covered in the following article Managing IBM App Connect API flows with embedded API management capabilities

Managing the API in IBM API Connect provides multiple benefits. It can:

  • allow different security policies to be applied to the API (including OAuth) and give control over who is consuming it.
  • provide management capabilities like rate-limiting.
  • provide lifecycle management and governance capabilities.
  • capture analytics data about the use of the API.
  • provide self service portals for publishing APIs for discovery and use.

While these won’t be covered in this article, details can be found in the API Connect knowledge center .

This article shows the steps to take a simple API created in App Connect and expose it in API Connect then call it via the built-in test tools.

The API in App Connect

App Connect offers the ability to expose a flow as a REST API. This section will cover navigating around the API and collecting the relevant details needed to call it including the API base URL, the operations paths and the request body details.

  1. In App Connect, navigate to a flow that was created via the “Create flows for an API” action. For details of how to do this see the tutorial.
  2. The API will be exposed via a combination of the base URL and the path section specific to each model. For example {API base url}/{path}
    1. The ‘Manage’ tab shows details connection details as well as the base URL of the API (in this example the base URL is: https://apis.appconnect.ibmcloud.com/JeigLU).
      This URL is only a base path, not an active endpoint and will return a 404. The active endpoint would be: https://apis.appconnect.ibmcloud.com/JeigLU/{path}This panel also contains the details needed for connecting to this API using basic auth credentials (the username and password fields).

    2. For details about the operations path and HTTP method, navigate to “Define” > “Operations”. In this example the HTTP method is POST and the path is /test1.
    3. Putting these together means that the full URL that the API will be exposed at is: https://apis.appconnect.ibmcloud.com/JeigLU/test1
  3. The panel “Define” > “Properties” show that properties that can be used with this model. In this example the “name” property has been defined, so the request body for this API would be:
    {"name":"Sample name"}
  4. This API can be called directly against App Connect using the details described above. An example curl command to allow this would be:curl -k -u appconuser01:12345ddd-9cde-4a8d-b2e2-f7ee7aaaa123 -X POST -H 'content-type: application/json' -d '{"name":"Sample name"}' https://apis.appconnect.ibmcloud.com/JeigLU/test1
  5. From the ‘Manage’ panel download the OpenAPI document using the ‘Download API’ button.

Manage the API in IBM API Connect

Using the OpenAPI doc downloaded from App Connect we are going to import the API into API Connect, make some updates to the API definition and test it, then expose it via the developer portal. For further details of features available in API Connect please view the API Connect knowledge center.

The OpenAPI definition downloaded from App Connect serves dual purposes of allowing the API to be called directly via OpenAPI/swagger tooling, but also being the starting point for importing the API into API Connect. As a result of this some minor changes need to be made to the API when it is imported to API Connect.

  1. In API Connect, import the API from the OpenAPI document and add it to a product. A product is the way of grouping together APIs to be published and discovered. The API Connect knowledge center defines products as:

    Products provide a method by which you can group APIs into a package that is intended for a particular use. Additionally, they contain Plans, which can be used to differentiate between different offerings. You can create Plans only within Products, and these Products are then published in a Catalog.

    1. Select “Drafts” > “APIs” > “Add” > “Import API from a file or URL”.
    2. Select the OpenAPI file that was downloaded from App Connect and give some details of the product that this API should be added to (in this example the new product will be called “test1_product”.
    3. Complete the action by clicking “Import”.
  2. Ensure that the API contains an assembly with a proxy policy pointing at the URL for the App Connect API (in this example the URL would be: https://apis.appconnect.ibmcloud.com/JeigLU/test1). This is an example of a very simple API which has only one path. The assembly would look different for more complex APIs.
    1. Select the “Assemble” panel.
    2. This action might require a new assembly to be created for this API. Click the ‘Create Assembly’ button if required.
    3. Add a Proxy policy to the assembly by dragging the ‘Proxy’ node onto the canvas.
    4. Set the properties on the proxy policy to:
      • Title: App Connect proxy
      • URL: https://apis.appconnect.ibmcloud.com/JeigLU/test1 (Taken from App Connect as shown above)
      • Username: appconuser01 (Taken from App Connect ‘Manage’ panel as shown above)
      • Password: **** (Taken from App Connect ‘Manage’ panel as shown above)
    5. Save the API changes by clicking the save icon in the top right hand corner.
  3. Make changes to the API definition. Select the “Design” tab.
    1. The OpenAPI being imported contains the host field which points at App Connect. While it is valid to set a host value when using App Connect, in this case we want this value to default to the relevant API Connect gateway that this API is deployed to. To do this navigate to “Design” > “Host” and ensure that the host field is “$(catalog.host)“.
    2. As we have configured the proxy policy with details of the system credentials (provided by App Connect) they don’t need to be passed in when calling the API. Disable this by navigating to “Design” > “Paths” > path name (for example “/test1”) > POST > “Security” and uncheck “basicAuth (Basic)”.
      Note: this disables security on this API and is only being done for demonstration purposes in this article.

      Specifying the App Connect credentials on the proxy policy allows the API Connect user to configure a security definition that is relevant to API Connect. For example it might make more sense for the user to provide their own credentials when calling the API (and API Connect could verify they are allowed to access it) instead of forcing them to provide the App Connect details.

      For more details of the security settings in API Connect view the knowledge center.

      The default settings for creating a new API from scratch is to require that an API key is present. This step is only being left out of this article for the sake of brevity.

    3. Save the API changes by clicking the save icon in the top right hand corner.

Test the API using the built in test tool

  1. Select the “Assemble” panel. Test the API by clicking the test button.
  2. Change the setup to select the product that was created when this API was imported (in this example test1_product) then republish the product.
  3. Select the correct operation (in this example “test1”).
  4. Generate the sample data using the “Generate” link.
  5. Test the API using the “Invoke” button. This should show that the API was successfully invoked.

Viewing the API in the API Connect Developer portal

This section assumes that a developer portal is already configured for API Connect. If this isn’t the case see the API Connect knowledge center.

  1. Navigate to the Developer portal and select “API Products”. This should display the product that was created when the API was imported (in this case “test1_product”).As part of the testing in the previous section, the product that contains this API will have been published. If this wasn’t the case (and the product isn’t in the list of API Products) then follow the steps to publish a product to a catalog

  2. Select the product then navigate to the API.
  3. The developer portal will contain details of where the API is deployed to along with information on how to call it and the chance to subscribe to it.

Conclusion

This article has outlined some of the key steps needed to expose an App Connect flow via API Connect. Now the integration flow has been exposed as a REST API and can be called externally. You are now able make use of the features that API Connect provides to improve the running, managing and securing of the APIs as well as allowing them to be discovered via the Developer Portal (For an overview of these features see the API Connect knowledge center).

There is a lot of scope for additional configuration (especially in API Connect) which have been deliberately skipped in order to keep this article shorter, however the key steps have been covered. We now end up with an API which is being managed by API Connect.

Join The Discussion

Your email address will not be published. Required fields are marked *