When should Decision Connect be used to expose managed API’s ?
As described in the Decision Connect article there are strong use cases when
- a business wants a central list or catalog of decisions it wants to manage across the enterprise
- a business has cloud based systems of engagement or cognitive applications or Processes that need to consume decision API’s
- a business wants to create composite API’s which include some decision API’s to monetize externally or use internally
There may additionally be some IT focused requirements to
1. There is an integration requirement for APIs to be implemented in a consistent manner using Swagger 2.0 to aid cloud integration.
2. There is a requirement for managed APIs with one or more of the following –
- a business requirement to improve efficiency re-use and time to market of solutions
- an integration requirement to improve developer experience in API re-use, introspection, testing
- a security and management requirement to control who gets access to re-use specific APIs at what rate, and what security is applied and enforced on each API
Capability and tools in API Connect v5 which is used as a fundamental part of Decision Connect to provide the foundation to address all three. To improve re-use tools to import, add metadata and publish to an API Catalog which improves visibility and efficiency. Developer tools to aid the developer experience to introspect, view and test API’s before using which can greatly enhance re-use. On the security, management and runtime enforcement aspects provide the ability to create API product and plans to manage the API from a subscription and rate of access perspective. The managed API can then be deployed to the API gateway to enforce.
Key steps to use Decision Connect for exposing managed decision API’s
There are six steps identified from creating a decision, publishing it as an API, creating a managed API from it to be published to an API catalog, to being introspected by application developers prior to selection and use in their solution.
If the reader is an existing ODM user with existing decisions it should highlight that there is additional tasks to be done to manage the decision API in an API lifecycle prior to being externalized using API Connect tools. This article and the articles it links to is designed as an introduction on what has to be done and how.
Additional understanding on how to use and install IBM API Connect V5 Essentials will also be required.
The article will cover this and also link to some detailed articles on individual stages.
The example uses the sample “miniloan” decision service in IBM ODM. Assume the requirement for this to be exposed comes from a one of the business use cases identified at the start of the article for example – system Of engagement or cognitive solution.
For users wanting to follow the example directly, then we recommend doing the “miniloan” Getting Started tutorial.
If you want to apply the steps to your own decision service then follow the steps omitting the basic tutorial.
1. Create Decision (Optional Step)
The miniloan decision is a decision service which provides certain business checking on whether a loan can be provided to a borrower. Its implemented using a combined validation decision and an eligibility decision integrated within it using ODM ruleflow capability.
It has a single decision interface (a decision operation) for applications / processes to pass a borrower and a loan request data fields.
The initial tutorial assumes that it has a web services interface automatically generated using ODM Hosted Transparent Decision Service (HTDS) . Use the ODM V8.8.0 Tutorial link
2. Select decision and create Swagger API
Using the miniloan example demonstrate how that single decision can be transformed from having a web services interface with HTDS to having a Swagger 2.0 API documented in YAML. This is a pre-requisite to allow it to be published into to the API catalog in Decision Connect capability (API Connect) or a separately purchased IBM API Connect V5 deployed elsewhere.
This could be done by the rule Developer or the rule administrator persona creating a new Swagger API file based on the REST based decision.
Detailed instructions in this article .
The value of doing this is the decision interface is being formatted in an OpenAPI industry format to publish and make it easier for developers to introspect, view, understand , test and finally re-use the decision service as you will find out in stage 5.
OpenAPI which defines Swagger requirements is supported by many companies including IBM. This also aids cloud based solutions re-using existing enterprise decision assets for new API based use cases.
The decision API can be consumed directly by a process or application, but it will not be managed in any way to enforce who can use it, at what rate can it be used, security policies which should be used with it, and it will not have the benefit of being available in an API catalog with easy to use tools to improve re-use.
If there is a requirement for managed API’s which provide better management and security using Decision Connect and its API Connect capability should be valuable.
3. Create a Managed Decision API – Import and Extend API Metadata
The initial step to manage an API is to import the decision based Swagger API into the API Connect capability with Decision Connect.
We also need to configure proxies to allow the API gateway on how to call the decision services running on ODM Decision Server you can configure.
API Connect developer tools support these tasks
Detailed instructions in this article.
4. Create API Product, Plans and Deploy and Enforce the Managed Decision API
To define who is authorized to access the Decision API and at what rate, one or more “Plans” are created which any API consumer application needs to subscribe to
Managed APIs may expose an API built from a single API, or a combination of APIs with some business logic integrating them which requires the concept of an “API Product” to be used to contain all the APIs required.
For each API Product we also need to manage who can view, use the API and at what rate in a plan or set of plans. The product, plans, who has subscribed to the API’s are all sent to the API Gateway to enforce.
At the end of this we have a managed decision API and product which is ready to be deployed to an API gateway. One of the extended value items which can be seen is that the tools already have automatically added stubs to demonstrate how the API can be invoked from Ruby, Python, PHP, Node.js and Java.
When the decision API is complete its deployed to the appropriate staged API catalog and has an approval step before its deployed to the relevant gateway for development , test or production configurations.
It’s a best practice to have the management role for API deployment separate from API creation and development
5. Cloud Developer uses API Tools to Introspect, View and Test Managed Decision API
One of the major benefits of managed API’s is that finding and introspecting APIs to re-use is not such a manual process. There is an API catalog which has published APIs along with plans which define who can access them.
APIs which have a public plan can be introspected by any developer. APIs with restricted plans may selectively provide access.
The cloud developer may have to contact their API manager if there are APIs in the catalog they are not authorized to use yet, or if there are new APIs which should be added to the catalog to allow the developer to use for new solutions.
Once the cloud developer logs into the API Connect Developer Portal if they are authorized to see the new decision API. It will look like the following when viewed
The description of the API and its inputs / outputs as per Swagger 2.0 and OPENAPI specification are easy to views along with the short examples of how to invoke in different environments.
There is a utility for the developer to test the API using the tooling prior to having to integrate into their application before use.
6. Cloud Developer integrates the Managed Decision API into the Cloud application
If the cloud developer is happy with the capability of the new decision API, they can implement the relevant API call within the application and test this full solution.
When working the cloud developer will finalize the application update and submit into the updated application life-cycle for test and production.