IBM API Connect | Cloud, pOrg, Catalog, Space, Plan usage recommendation
Introduction:
The IBM APIConnect v10 CLoud has several Configuration which can be used to logically segregate the usage across Envrionments or Department or Business Units within the Enterprise.
This article covers logic behind the segregation with typical approaches followed by Clients
APIC Cloud:
The APIC Cloud is top level of segregation. An APIC Cloud is an entire API Connect physical setup. If physical isolation is required between layers then multiple API Clouds will be designed and deployed. Each API Cloud requires their own Portal, Gateway and Analytics services, these cannot be shared.
Note: If you had opted for single APIC Reserved Instance for all environments, there is only one APIC Cloud.
APIC Provider Organization:
A Provider Organization(pOrg) is a logical entity within an API Cloud. An API Cloud can contain multiple Provider Organizations; however, a Provider Organization can only exist in a single API Cloud and Not span/sync across multiple APIC Clouds
· Each pOrg has a designated organization owner, who is assigned during pOrg creation from the Cloud Management console. The owner is in charge of the initial configuration and user on-boarding for that pOrg.
· There is complete isolation from other pOrg. The APIs and resources created in one pOrg is NOT visible or accessible in another pOrg.
· Each pOrg can be accessed using the API Manager UI. Users (API Developers, Admin) can belong to multiple pOrg, with different roles and corresponding permissions set.
· Provider Organizations can be named after an environment or by an Organization’s business unit.
· The pOrg segregation has an impact on the actual API endpoints that are created. API naming follows the following scheme within API Connect: https://<Gateway-Host>/<pOrg-name>/<CatalogName>/apibasepath/apirsrcpath
· Thus, not only do pOrg impact API consumption, but also impact logical partitioning on the API Gateway assuming the same API Gateway(DataPower) instance is shared between multiple environments.
Typically, Clients create pOrg for each Environment e.g. DEV, SIT, UAT. This will help in Developers getting complete access to DEV pOrg. But SIT, UAT will have restricted access only to Operations Team.
In PROD if the APIC Cloud itself is different, the APIC Connect Cloud will host only LIVE environment pOrg with access only to operations team.
APIC Catalog
The Catalog is where API Publishing and Consumption is handled and a Catalog has a one to one relationship with a Portal Site.
a) if you have different set of COnsumers and you want to maintain different portal site for each, then it can be done using different Catalog creation within same environment.
b) if you have same/different set of Consumers and you want to maintain only one Portal site for all per environment, then create only one Catalog.
An API Product is staged and Published to a Catalog, which send the API Artefacts to the corresponding Portal site and API Gateway Services. There can be more than one API Gateway Service associated with a Catalog (e.g. DC Gwy Services, DR Gwy Service, Internal Gateway service, External Gateway Service etc.)
The Catalog segregation has an impact on the actual API endpoints that are created. API naming follows the following scheme within API Connect:
https://<GatewayHost>/<pOrgname>/<CatalogName>/apibasepath/apirsrcpath
Thus, not only do Catalog impact API consumption, but also impact logical partitioning on the API Gateway assuming the same API Gateway(DataPower) instance is shared between multiple environments.
Note: If same Catalog name is used for all pOrg, and if you want to reduce the complexity for DevOps by leveraging the API Properties feature then prefix/suffix Env code in each Catalog name.
Options:
External, Internal, Public, Private, Partner, Common etc.
APIC Spaces
When multiple development/deployment teams are working with in the same Catalog it is very easy for mistakes to happen. In order to provide better control of a Catalog, Spaces can be used to segregate them. Spaces provide a RBAC for APIs Product Lifecyle management. Each Development/Deployment team part of a Provider Organization would be given a space in each Catalog they are using.
Options:
Team 1, Team 2, Dept 1 , Dept 2 etc.
APIC Products
Products are a logical grouping of APIs and Plans. If API security is enabled, APIs can be invoked once a Consumer Organization has subscribed to a plan. If no API security is enabled, then the APIs can be invoked immediately after publication.
The purpose of a Product is to tie APIs together for a similar set of use cases. The Product must accurately describe the purpose of the collection of APIs it contains.
Though there is no technical limitation for the number of APIs in a product, from a management and governance perspective it is recommended to have no more than seven APIs and three Plans per Product.
Product names should include dashes and not underscores and should not contain numbers. Version numbers should not be defined in the Product name i.e info.title or info.x-ibm-name, this causes confusion as it is static against the dynamic version number that displays next to the Product i.e. info.version.
APIC Plan
Plans are used for rate limiting of API Calls and approval for subscription. it can be used for monetization of APIs as well. Developer(a.k.a Consumer)Organization subscribe an Application to a Plan within a Product.
If all API referred in a Product -> Plan has same API Security, then once the Consumer Org subscribes to Plan, they will be able to access all APIs under the Plan. Thus, it’s important to group the APIs to Plan in a Product carefully.
Plans have the additional functionality of burst limits which is designed to protect both the api infrastructure and downstream application which can then be configured per api within the same product. Each product can have multiple plans which will have different costs and appropriate rate limits. Additionally, different plans may conform to predefined contract agreements between third parties, public and internal users.
Thus, it’s important to have logical grouping of APIs and their rate/burst limits identified, these should be reflected in Plan names. This would typically map to a standard selection of upgrades.
Options for Plan can be:
1. Basic | Standard | Advanced
2. Silver | Gold | Platinum
3. Small | Medium | Large
Versioning: refer this article
Disclaimer: The info in this article is compiled based on multiple project experience and different product documentations. Clients using APIC can use these for reference and can alter based on their specific requirements.
