What is IBM API Connect?

API Connect is a platform to create, manage, and securely socialize information via APIs. This centralized platform allows multiple API providers to deliver services and portals to their customers both inside and outside the organization.

API Connect is made up of:

• An API manager for managing API creation, publishing, communities, subscriptions, and exposure.

• An API gateway for managing and enforcing API traffic, rate limits, throttling, and security.

• A developer portal where consumers can explore APIs, subscribe through free or paid-for memberships, create applications and generate credentials, and learn more about the APIs that they are using and consuming.

• API Analytics for monitoring API usage and responses on individual gateway servers or across a gateway cluster. This is its own container(s) in v2018 but resides inside the management server in v5.x

What is an Extension?

To support requirements, you can extend the gateway servers within IBM API Connect to provide extra enforcement behaviour which allows policies to be applied through domain wide hooks in the following parts of the API flows:

• Before the request is processed (Pre-Request)

• After the request has been processed but before API assembly invocation (Post Request)

• After a response has been generated by the API (Post Response)

• After an error response has been generated by the API (Post Error)

Extensions can also be used to define persistent changes to DataPower domain properties such as:

• Log Targets

• MQ Objects

• Payload Limits

Why do we update Extensions?

Extension updates are made when custom code needs to be written across a domain. This might come for a number of reasons, such as; changes in regulatory requirements, changes in internal requirements, a need for greater error handling after API Connect assembly or changes in objects deployed onto DataPower that need to be persisted.

Update Considerations

• By Default, all servers in a DataPower Service cluster are refreshed when an extension file is updated

• If a DataPower server is refreshed in API Connect, any manual changes made on the domain (not in the Extension) might be lost

• Extensions changes can affect all APIs associated to the DataPower Service (domain) being deployed to

• After Extensions are deployed, all servers in the DataPower Service cluster must be refreshed

• A toggle button in the CMC when uploading Extensions allows for the refresh of servers in a cluster to be either manual or automatic

• In Active-Active architectures, server refreshes can be applied to a single datacentre at a time. This might be achieved by restricting access to a single datacentre at a time to limit customer impact.

Automatic Refresh vs Manual Refresh

The default behaviour when updating Extensions is for each of the gateways in the DataPower Service to Automatically refresh. This means that when changes are applied in the CMC, the gateway servers are unable to serve traffic because the domain is deleted on all the gateway servers by the manager before being added back in (synchronised).

This automatic process means that traffic cannot reach the domain (whilst deleted) causing a service outage and a staggered increase in availability as each domain is added to each server synchronously. This reduces control of traffic flow and availability of services although is a simpler process if service outages can be tolerated.

In APIC 5084+ a Manual Refresh option has been added in allowing for greater control when servers get the latest code and can help avoid service outage. We discuss below how this feature can be used in practice.

Update Procedure with manual refresh option

Pre-Requirements:

• The new extension file either through a .zip file or pipeline tooling

• The current extension file either through a .zip file or pipeline tooling

• Any post deployment files that are needed in the domain i.e. keys and certificates

Procedure:

1. 1. Take a backup of all existing configurations; including DataPower Servers and API Connect using the API Manager CLI commands
   2. Run sanity tests on all APIs in the current domain
   3. Login to the Cloud Manager Console as admin
   4. Go the relevant DataPower Service
   5. Press the Settings - Cog icon
      1. Deselect the “Automatically refresh extension on gateway servers” toggle
      2. Select “Replace this extension” button, browse for the latest extension and select “upload”
      3. Select “Save Configuration” only save after completing both a and b
   6. The Service will update and show the gateway server(s) as ‘out of sync’
   7. Resync and test each server in the cluster
      1. delete a single “out of sync” server
      2. re-add the deleted server with the same settings
      3. Upload post deployment files into the domain
      4. Run sanity of all the APIs tested in Step 1
   8. If successful, Repeat for all remaining servers

NOTE: Deselecting the “Automatically refresh extension on gateway servers” is a per deployment setting so MUST be selected for every deployment, else all servers will refresh automatically.

Rolling back if there are issues

For all error types the following logs should be obtained:

• DataPower error report

• CMC post mortem from the CLI

• DataPower Logs

Server Error:

1. Double check server settings for mistakes when re-adding the server
2. Check the DataPower and API Manager ‘cmc.out’ logs for obvious issues i.e. missing certificates
3. Ensure all post deployment files have been added to the domain
4. If still failing, repeat Manual Update Procedure with ‘current’ working extension
5. If still failing, refresh the failing server from DataPower Server backup
6. If still failing, refresh the API Connect from its backup file

API Error:

1. Check DataPower logs for obvious errors - client id valid, client secret valid etc.
2. Enable the probe in the relevant domain
3. Complete a failing API call
4. Export the probe for later analysis
5. Repeat Manual Update Procedure with ‘current’ working extension

Multi Data Centre Update Scenario

Scenario:

A customer has an API Connect setup with 4 DataPower servers with 2 servers per data centre. Traffic to the cluster is controlled by a load balancer. API Connect has a DataPower Service defined in the Cloud Manager Console (CMC) with all 4 DataPower servers added, this API Connect configuration is pushed to the 4 DataPower Servers into a domain.

Procedure:

1. After backups and sanity tests have been completed the load balancer is routing traffic to both data centres and all the servers show as ‘ACTIVE’ in the CMC
2. The extension is deployed to the relevant domain as described in the ‘Manual Update Procedure’ section, this puts the 4 DataPower Servers ‘OUT OF SYNC’.
   All traffic continues to run on the previous version of the extension
3. Traffic is disabled from entering Data Centre 1 at the load balancer level, traffic continues to be served by Data Centre 2
4. Data Centre 1 servers are deleted from the DataPower Service
5. Data Centre 1 servers are added to the DataPower Service
6. Data Centre 1 servers will display as ‘ACTIVE’ and Data Centre 2 servers will display as ‘OUT OF SYNC’
7. A test runner makes API calls to Data Centre 1
   In the event of a failure the ‘Rolling back if there are issues’ section should be followed
8. Data Centre 1 servers will now be implementing the new version of the extension and Data Centre 2 servers will be implementing the current version of the extension
9. Traffic is disabled from entering Data Centre 2 at the load balancer level, traffic continues to be served by Data Centre 1
10. Data Centre 2 servers are deleted from the DataPower Service
11. Data Centre 2 servers are added to the DataPower Service
12. All Server will not display as ‘ACTIVE’
13. A test runner makes API calls to Data Centre 2
    In the event of a failure the ‘Rolling back if there are issues’ section should be followed
14. All servers will now be implementing the new version of the extension

Conclusion

Extensions are an extremely useful tool to be used by API development team allowing for global policies to be applied across a whole domain, but there can be risks. It is important that a procedure has been defined that works for each customer and that the procedure has been tested in a safe environment.

Hopefully this document has given a greater understanding of how extension updates are achieved, why they are important and how to rollback if an issue is faced in the procedure.