Skip to main content

Managing API groups

What is an API group?​

An API group is a meta-API that allows you to group multiple APIs together based on their usage. While it was initially designed to group related use cases, in practice, it serves primarily as a visual wrapper that provides a unified entry point for multiple related APIs.

An API group is built similarly to a regular API—it displays a description, documentation, and an OpenAPI definition. However, it also allows users to dive deeper and access the individual APIs within the group separately.

Key characteristics​

Visual grouping​

API groups provide a cohesive presentation layer for multiple APIs, making it easier for consumers to discover and understand related services.

Independent subscriptions​

Subscriptions to an API group are completely decoupled from the underlying APIs. Each has its own plans and Otoroshi targets, meaning:

  • Subscribing to the group doesn't automatically grant access to individual APIs
  • Each API maintains its own subscription flow and authorization rules
  • Plans and billing are managed independently

Producer permissions​

Only API producers can add their APIs to a group. This ensures that teams maintain control over how their APIs are presented and grouped.

Create a new API group​

To create a new API group, click on the + Create an API button displayed on dashbaord and then create as APIgroups.

Basic information​

An API group is basically an APi, it need same informations to be created.

Grouping APIs​

The main difference from a regular API is the ability to reference multiple APIs within the group:

  1. Navigate to the APIs section in the API group configuration
  2. Select the APIs you want to include in this group
note

You can only add APIs that your team owns.

Individual API access​

When consumers view an API group, they can:

  • See the group's overview and documentation
  • Browse the list of APIs included in the group
  • Access each individual API's detailed page
  • Subscribe to the group or to individual APIs separately (if it's possible)

Subscription management​

API group subscriptions work independently from individual API subscriptions:

  • Group plans: Define quotas, pricing, and validation steps for the group as a whole
  • API plans: Each API maintains its own plans and subscription process
  • No inheritance: Subscribing to a group doesn't automatically provide access to its APIs

Use cases​

API groups are particularly useful for:

  • Domain-based grouping: Group all APIs related to a specific business domain (e.g., "Payment APIs", "User Management APIs")
  • Product bundles: Create logical product offerings that span multiple technical APIs
  • Versioning strategies: Group different versions of related APIs
  • Documentation organization: Provide a single entry point for complex, multi-service architectures

Best practices​

  • Clear naming: Use descriptive names that immediately convey the group's purpose
  • Coherent grouping: Only group APIs that are logically related
  • Comprehensive documentation: Explain how the APIs in the group work together
  • Independent but aligned: While subscriptions are independent, consider aligning plans and pricing for consistency
  • Regular updates: Keep the group's API list up to date as your architecture evolves