Introduction

Increasingly, businesses are looking to automate their enterprise platforms as a means of accelerating and controlling deployment. There is also a requirement for accessing the server for administration, development and operation without using the UI, for security or usability preferences for example. To achieve this, it is crucial to have product tools that can interact with the platform to replicate the functions typically performed on the UI. For API Connect, several tools are available including the platform REST API, toolkit CLI and more recently the API/Product CRs. This article compares the methods, to help teams select a tool that best aligns with their needs and cultures.

An overview of the tools

The API Connect toolkit CLI is a binary available from IBM Fix Central, specific to the product version deployed. Instructions for installing the toolkit are available here: https://www.ibm.com/docs/en/api-connect/software/10.0.8_lts?topic=configuration-installing-toolkit. Once installed, the APIC interface can be interacted with using the toolkit from the command line or via a pipeline script.

The API Connect REST API is available in API Connect v10 and can be used to interact with the APIC interface using REST API calls without the need to download a specific binary. There is comprehensive documentation available here: https://apic-api.apiconnect.ibmcloud.com/v10/#/documentation/introduction.

The API/Product CRs are the latest introduction as part of IBM Cloud Pak for Integration which allow creation of API Connect APIs and Products using Kubernetes custom resource objects. Documentation for this is available here: https://www.ibm.com/docs/en/cloud-paks/cp-integration/16.1.1?topic=pak-using-api-api-product-kubernetes-resources.

API Connect toolkit CLI

The toolkit CLI provides a mechanism to perform administrative and development operations in API Connect without requiring direct interaction with the UI. The toolkit first requires the user to login to the API Connect server using the CLI, following which commands can be run such as creation of catalogs and publishing of APIs. The toolkit is powerful in that it can accomplish virtually any operation that would normally be performed in the UI. There are some practical considerations when using for automation:

• Any pipeline script must have access to the toolkit CLI

• Managing and manipulating response objects can be more difficult in scripting than with using the REST API

• Can require deeper API Connect product knowledge

API Connect Platform REST API

The Platform REST API available in version 10 of the product can achieve the same level of functionality as the toolkit CLI can. Unlike the toolkit, it is more lightweight because the toolkit binary does not need to be made available to the automation pipeline. It may also be more familiar to users than the toolkit CLI as it uses standard REST API operations that do not necessarily require extensive product knowledge. This can also make it easier to integrate via scripting. The documentation is extensive which furthers its usability.

The key practical consideration is that the platform REST API cannot be used completely standalone. An Application must be created as a one-off task and then used to generate a Bearer Token before access to the REST API is granted. However once the Bearer Token is generated the REST API is completely standalone, until the Bearer Token expires. The Application must be reused to generate a fresh Bearer Token for every subsequent use of the REST API once the previous Bearer Token has expired. There is also an idempotency consideration. For example, if an API that already exists is attempted to be created using the platform REST API (or toolkit CLI), there will be an error response instead of gracefully skipping over it. This can require additional logic to compensate for.

API/Product Custom Resource

As of Cloud Pak for Integration v2023.2.1, custom resources (previously used for installing the infrastructure sub-systems), can be used for creating APIs and Products on API Connect. The advantages are that the CRs can be stored in source control providing an accurate reflection of what is deployed in the environment. Additionally, the APIs and Products deployed, reflect the state of the CRs so if they are changed elsewhere (such as in API Manager), the CR will revert them back. APIs and Products can also be rapidly deployed across systems using automation tools such as ArgoCD.

The considerations with the CR are that they are only available as part of Cloud Pak for Integration and are limited to the management of APIs and Products. Other API Connect operations would require an alternative tool.

Choosing a tool

When deciding which tool might be most appropriate, the following can be considerations:

• Is there a particular tool or technology that the team are more familiar with?

• What does the tool need to be able to do?

• What other products are being used (for example is Cloud Pak for Integration being used?)

• Is the tool for automation or manual operation? (the toolkit CLI may be preferred as a manual tool, whereas the platform REST API may be more automatable)

• How familiar are the team with the API Connect product?

Review and recommendations

Familiarity with certain technologies can be key in selecting a tool. For example, if a team is particularly experienced with API Connect, they may prefer more traditional methods such as the toolkit CLI. Whereas if the team are heavy users of Kubernetes, they may prefer using the declarative API/Product.

It may also depend on how extensive the operations that the tool is required for are. The declarative API may be an excellent choice if teams are simply looking to deploy APIs and Products, but for wider management the toolkit CLI or platform REST API might be opted for.

From experience, the preferred tool when automating API Connect platforms is the platform REST API. This is due to its lightweight integration with scripting, comprehensive operations, extensive documentation and relative ease at managing and querying response objects as part of a multi-step automated operation. For manual tasks, the toolkit CLI is preferred due to its relative ease of putting CLI queries together as opposed to REST API requests, and particularly if the team has high levels of experience with API Connect.

Conclusion

API Connect provides excellent tooling for interacting with the server without using the UI. There are many factors that should be considered when selecting a tool. It is also not an either/or scenario; different tools could be selected for different business requirements. Selecting the correct tool is important in maximising the advantages of it for administrative and/or development purposes.