API overview

The App Connect API provides access to resources in your instance. The API provides a way to administer BAR files, configurations, integration runtimes, and trace.

You typically use the API to automate the deployment lifecycle of your integrations from continuous integration and continuous delivery (CI/CD) pipelines. This API supports create, read, update, and delete functions for App Connect resources. For example, to deploy an integration, you can use the API to create an integration runtime by providing a BAR file and configurations. You can download an OpenAPI file that describes the API specification from the Public API credentials page App Connect. The Public API credentials page is in the Connect category Icon that represents the Connect category. of the navigation pane.

Endpoint URLs

To form the complete URL of an API endpoint, identify the base URL for your service instance, then add the method.

The URL of the API for your App Connect instance is https://api.region.appconnect.ipaas.automation.ibm.com, where region is the region where your instance is hosted. You can find the region (such as a-vir-c1) in the URL for your instance.

You can also generate this URL in the OpenAPI file by selecting your region.

The base URL for the App Connect API endpoint is https://api.a-vir-c1.appconnect.ipaas.automation.ibm.com. When you call the API, add the path for each method to form the complete API endpoint for your requests. The following example shows the URL for integration runtimes.
https://api.a-vir-c1.appconnect.ipaas.automation.ibm.com/api/v1/integration-runtimes

Authentication

You authenticate to the API by using an access token. To generate the access token, you create an API key, a client ID, and a client secret. Tokens support authenticated requests without the need to embed service credentials in every call. The access token is valid for 12 hours after which time you must get a new token. For subsequent calls to the API, you use the X-IBM-Client-Id header to provide your client ID, and the Authorization: Bearer header to provide this access token.
Note: Authorization: Bearer is case-sensitive and must be referred to in calls with the correct capitalization.

For more information, see Accessing the API with a personal API key.

Response codes and error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200-type response indicates success; a 400-type response indicates a failure; and a 500-type response indicates an internal system error.

Rate limits

The rate limit is the maximum number of calls that you can make to the API in a particular time interval. You can send 100 requests in a 5-minute interval to the API for your instance. This limit applies to all client IDs on your instance.

If you reach 100 requests in a 5-minute interval, HTTP response code 429 is returned, and no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.

The response to each HTTP request includes the following headers that you can use to determine whether you are close to the rate limit.
  • X-RateLimit-Reset indicates the time when the current timer expires (in UNIX epoch time).
  • X-RateLimit-Remaining indicates the number of requests that remain in the current time window.
  • X-RateLimit-Limit indicates the total number of requests that are allowed within the time window.