Versions overview

This page applies to Apigee and Apigee hybrid.

Every API resource in API hub has at least one version associated with it. You can think of a version as the state of an API at a point in time. Fundamentally, versions help you group and organize your APIs based on underlying sets of operations or tools, deployments, specifications, and other attributes.

In API hub, a version represents a logical grouping. For a REST API, this grouping usually revolves around the operations it can perform. For example, the first version of a Pet Store API might let you perform basic tasks like adding a pet, finding a pet, and deleting a pet from the store. For an agentic API using the Model Context Protocol (MCP), a version would be grouped around a set of tools that an AI agent can use.

It's a good practice for a version to include a set of API operations or tools that are deployed together. For example, a pet store API might have a version that includes add, find, and delete functions, all deployed to the same environments.

Creating versions

If the details of an API you want to add to API hub are captured in a specification file, you can add the spec to an API version. When you do, API hub parses the spec and pulls information out of it.

  • For a REST API, API hub parses an OpenAPI spec and uses it to populate the version with the operations the API includes.
  • For an MCP API, API hub parses an MCP Schema file to extract its tools

If you don't have a supported specification file, you can still create a version, but you'll have to populate it manually with relevant descriptive information. Another case where API hub supports automatic parsing of API details is through the auto-registration of Apigee API proxies.

When to create a new version?

If new operations or tools are added to an API, it may warrant creating a new version, but not always.

Let's say the API producer adds a new function to an API and intends for it to be deployed to all of the deployments currently associated with the version. In that case, the producer may choose not to create a new version of the API. On the other hand, if the producer makes a backwardly incompatible change (a breaking change) and chooses to associate it with a new deployment, you may wish to create a new version.

You can see that API hub provides flexibility for you to define and organize your API versions to best suit your organization's needs and the needs of specific API producers.

What's next