IBM Integration User Group UK

 View Only

Organizing teams in APIC - Provider Orgs, Catalogs and Spaces

By Aiden Gallagher posted Thu July 18, 2019 09:37 PM


There are many ways to split and organize teams in IBM API Connect but there are some considerations which can influence the decisions when deciding whether to split at the Provider Organization, Catalog or Space level. 

Architectural Overview

Architectural Topology Overview

    • Catalogs have a 1:1 mapping with Developer Portals

    • Catalogs can be separated into Spaces

    • Traffic can be isolated between spaces

    • Provider Organization can have many Catalogs and each Catalog can have many Spaces

    • Enabling Spaces in a Catalog is permanent

    • You cannot migrate spaces from one Catalog to another

    • Communities are Catalog defined objects used to manage API Consumers

    • Product Plans can be used to set community visibility and subscribability within a Developer Portal

We will now look at specific points for each of the levels in the hierarchy individually – Organizations, Catalogues and Spaces 


At the organization level you can do the following:

    • define roles and responsibilities

    • create, delete, edit all catalogs and spaces

    • add, remove users and assign or remove roles

    • billing configuration

    • create TLS Profiles - (certificates are exposed to all catalogs/spaces in the org)

    • associate User Registries

    • explore APIs

    • view security notifications such as; changes to user roles or the publishing of APIs etc.

    • An organization must have at least one catalog for API deployment

Organizations should be used for groups that want to remain independent from one another. They are commonly used as a separation of brands within an organization or to split API Management environments for a route to live. i.e. System Integration Test, User Acceptance Test etc.  

Case Study - An organisation with a single API Connect Cloud system uses Provider Organizations to split by environments with Dev, Test, SIT and Production each having their own Provider Organization. The teams within each organization share TLS Profiles for downstream services calls and a shared Active Directory user registry which is managed by an IBM API Connect infrastructure team. 


Note that Catalogs inherit default settings from the organization level.

Catalog Topology

At the catalog level you can do the following:

    • set up Gateway Services (channels) – which are then available to all spaces

    • update roles and responsibilities at the catalog level

    • Catalog owners/managers can create, delete, name and assign gateways for all spaces in the Catalog

    • create a Portal site (exactly one portal per Catalog)

    • create User Defined Policies to be used by all catalog APIs

    • deploy and manage APIs independently from other catalogs

    • add, remove and change the roles of users

    • community management (Consumer Orgs, Apps, Spaces, Subscription and approval). Note that applications cannot be shared across multiple Catalogs

    • view Catalog wide analytics data

    • create and manage ‘communities’ used in product plans to determine visibility and Subscribability for API Consumers within the developer portal

Use Catalogs to split teams who wish to expose API’s onto different portals and when a central team is managing lots of teams. These will be logically joined teams that will reuse security profiles and reusable functionality at the traffic level

Case Study - An Organisation team uses Organizations for each route to live environment i.e. Dev, Test, Prod with two levels of services; external facing, internal facing. Each exposes APIs in an isolated way through independent Developer Portals which require separate login methods. They use Catalogs to achieve this goal with APIs deployed to the relevant Catalogs. Approval processes are different for the two API deployment flows and a more diverse role set is required for the external facing APIs. 


Note that Spaces inherit default settings set at the catalog level

Space Topology 

At the space level you can do the following:

    • assign Gateway Services (channels) to spaces

    • set roles and responsibilities

    • select catalog level gateway services to be used for each space to give traffic level isolation for each space (all catalog services are enabled by default)

    • API deployment and management independent from other spaces

    • user management at the space level

    • community management specific to the space (Consumer Orgs, Apps, subscription and approvals)

    • view analytics data for the space 

Use Spaces to isolate teams exposing APIs in the same Portal, use where a central team is managing many sub teams who are themselves managed as part of a wider set of teams at the catalog level.

Case Study - An Organisation wishes to deploy their full set of APIs to a single Catalog to consolidate management of their portals to a single dedicated portal team. They also believe a single portal improves the customer experience. To achieve this, they use a single Catalog in a single Provider Organization for Production. They also have a requirement to segregate traffic using isolated gateway clusters for different teams, which they achieve using spaces. The Catalog defines the gateways to be used and each space enables only the required gateway cluster.

Decision Matrix for Orgs, Catalogs and Spaces: 

‘One Portal’ for all API Exposure?

Centrally managed/supported Infrastructure?

i.e. analytics, user management etc.

Isolated and Independent development teams?

Isolation of billing, security, roles and registration?






























Mon September 16, 2019 07:20 AM

Hi Colin,

That's right - I would note though that the portal is also important here due to the 1:1 mapping between a catalog and a portal. If you need one portal for all APIs you will have to use a single catalog to expose them all. Thanks for reading!

Fri September 13, 2019 12:34 AM

Great Article! Aiden

Looking at the decision matrix, can I distill it down to

a) if isolated and independent development teams are needed, use Spaces?
b) if isolated and independent development teams are not required, use Catalogs?
c) if isolation of security, roles and registration are needed, use Organisation(s)?