This page applies to Apigee and Apigee hybrid.
This topic explains what you need to know about creating and managing versions in API hub.
What is a version?
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, deployments, specifications, and other attributes, as shown in Figure 1.
Figure 1. Each version can have operations, deployments, and other attributes.
In API hub, a version represents a logical grouping of APIs. Usually, but not necessarily, this grouping revolves around the operations an API can perform. For example, let's say you have a Pet Store API, and the first version of this API lets you perform basic tasks, like adding a pet, finding a pet, and deleting a pet from the store. These are examples of operations.
It's a good practice for a version to include a set of API operations that are deployed together. For example, a pet store API might have a version that includes add, find, and delete operations, all deployed to the same environments.
Another good way to think about a version is that it represents the API producer's view of the API. It's the collection of features and capabilities that the people who built the API put into it and expect to be deployed with it.
Creating versions
Suppose the details of an API you want to add to API hub are captured in an OpenAPI spec. If so, you can add the spec to an API version. When you do, API hub parses the spec and pulls information out of it, such as which operations the API includes, and stores that information with the version. If you don't have an OpenAPI spec, you can still create a version, but you'll have to populate it manually with relevant descriptive information. One other case where API hub supports parsing of API details through the auto-registration of Apigee API proxies.
You can upload multiple API specification files to the same version.
When to create a new version?
If new operations are added to an API, it may warrant creating a new version, or perhaps not.
Let's say the API producer adds a new operation to an API and intends 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.
System attributes
Versions include the following system attributes by default. You can modify the values associated with these attributes in Settings. For details, see Manage attributes.
| Attribute | Description |
|---|---|
| Lifecycle | Lifecycle refers to an ordered set of stages that an API should progress through, from conception to end-of-life. Since each version of an API usually moves through its own lifecycle separately, we don't directly set the lifecycle stage of an API, but instead allow each API version to have an assigned lifecycle stage. |
| Compliance | Through Settings, you can define values to represent the compliance details of interest to your team or organization. For details, see Manage attributes. |
| Accreditation | Through Settings, you can define values to represent the accreditation details of interest to your team or organization. For details, see Manage attributes. |
| Documentation | A link to documentation for the API to which the version is attached. |
User-defined attributes
Depending on your team or organizational needs, you can define custom attributes (name/value pairs) for versions. See Manage attributes.