API Hub 中的每个 API 资源都至少有一个与之关联的版本。您可以将版本视为 API 在某个时间点的状态。从根本上说,版本可帮助您根据底层的操作、部署、规范和其他属性集对 API 进行分组和整理,如图 1 所示。
图 1. 每个版本都可以具有操作、部署和其他属性。
在 API Hub 中,版本表示 API 的逻辑分组。通常(但不一定)此分组围绕 API 可以执行的操作进行。例如,假设您有一个宠物商店 API,并且此 API 的第一个版本可让您执行基本任务,例如添加宠物、查找宠物以及从商店中删除宠物。这些是操作示例。
最好是让一个版本包含一组一起部署的 API 操作。例如,宠物商店 API 可能有一个包含添加、查找和删除操作的版本,这些操作均部署到相同的环境。
考虑版本的另一种好思路是它代表 API 提供方对 API 的了解。版本是构建 API 的人员在 API 中加入并希望与其一起部署的特性和功能的集合。
创建版本
假设在 OpenAPI 规范中会捕获您要添加到 API Hub 的 API 的详细信息。如果是这样,您可以将规范添加到 API 版本。执行此操作时,API Hub 会解析规范并从中拉取信息(例如 API 包含的操作),并将这些信息与版本一起存储。如果您没有 OpenAPI 规范,您仍然可以创建版本,但必须使用相关的描述性信息手动填充。API Hub 支持通过 Apigee API 代理自动注册来解析 API 详细信息的另一种情况。
您可以向同一版本上传多个 API 规范文件。
何时创建新版本?
如果向 API 添加了新操作,则可能需要创建新版本,也可能不需要。
假设 API 提供方向某个 API 添加了新操作,并打算将其部署到当前与该版本关联的所有部署。在这种情况下,提供方可以选择不创建该 API 的新版本。另一方面,如果提供方进行了向后不兼容的更改(重大更改),并选择将其与新部署相关联,则您可能需要创建新版本。
您可以看到,API Hub 可让您灵活地定义和组织 API 版本,从而最好地满足您的组织的需求和特定 API 提供方的需求。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC):2025-08-28。"],[[["\u003cp\u003eAPI hub utilizes versions to represent the state of an API at a specific point in time, allowing for the organization of APIs based on operations, deployments, and attributes.\u003c/p\u003e\n"],["\u003cp\u003eA version in API hub is a logical grouping of APIs, usually centered around the operations an API can perform, such as adding, finding, and deleting a pet in a Pet Store API example.\u003c/p\u003e\n"],["\u003cp\u003eAPI hub allows the addition of OpenAPI specifications to an API version, from which it will automatically extract information, although versions can also be created manually and populated with relevant information.\u003c/p\u003e\n"],["\u003cp\u003eNew versions of an API may be created when new operations are added or when there are backwardly incompatible changes, particularly if the changes are associated with new deployments.\u003c/p\u003e\n"],["\u003cp\u003eEach API version has system attributes like Lifecycle, Compliance, Accreditation, and Documentation, which can be customized, and users can also define their own custom attributes for each version.\u003c/p\u003e\n"]]],[],null,["# Versions overview\n\n*This page\napplies to **Apigee** and **Apigee hybrid**.*\n\nThis topic\nexplains what you need to know about creating and managing versions in API hub.\n\nWhat is a version?\n------------------\n\n\nEvery API resource in API hub has at least one version associated with it. You can think of a\nversion as the state of an API at a point in time. Fundamentally, versions help you group and\norganize your APIs based on underlying sets of operations, deployments, specifications, and other attributes, as shown\nin Figure 1.\n\n**Figure 1.** Each version can have operations, deployments, and other attributes.\n\n\nIn API hub, a version represents a logical grouping of APIs. Usually, but not necessarily, this\ngrouping revolves around the operations an API can perform. For example, let's say you have\na Pet Store API, and the first version of this API lets you perform basic tasks, like adding\na pet, finding a pet, and deleting a pet from the store. These are examples of operations.\n\nIt's a good practice for a version to include a set of API operations that are deployed\ntogether. For example, a pet store API might have a version that includes add, find, and\ndelete operations, all deployed to the same environments.\n\nAnother good way to think about a version is that it\nrepresents the API producer's view of the API. It's the collection of features and\ncapabilities that the people who built the API put into it and *expect to be deployed\nwith it*.\n\nCreating versions\n-----------------\n\n\nSuppose the details of an API you want to add to API hub are captured in an OpenAPI spec.\nIf so, you can [add the spec\nto an API version](./manage-specifications#addspec). When you do, API hub parses\nthe spec and pulls information out of it, such as which operations the API includes, and stores that\ninformation with the version. If you don't have an OpenAPI spec, you can still [create a version](./manage-versions#addversion), but you'll have\nto populate it manually with relevant descriptive information. One other case where API hub\nsupports parsing of API details through the [auto-registration of Apigee API proxies](./auto-register-apigee-proxies).\n| **Note:**API hub only supports the parsing of OpenAPI specs.\n\n\nYou can upload multiple API specification files to the same version.\n| **Note:**API hub cannot guarantee the stability of an API provided by an API producer. API hub assumes that all operations contained in an API version are intended to be deployed together.\n\n### When to create a new version?\n\n\nIf new operations are added to an API, it may warrant creating a new version, or\nperhaps not.\n\n\nLet's say the API producer adds a new operation to an API and intends it to be deployed to all\nof the deployments currently associated with the version. In that case, the producer may choose\nnot to create a new version of the API. On the other hand, if the producer makes a backwardly\nincompatible change (a breaking change) and chooses to associate it with a new deployment,\nyou may wish to create a new version.\n\n\nYou can see that API hub provides flexibility for you to define and organize your API versions\nto best suit your organization's needs and the needs of specific API producers.\n\nSystem attributes\n-----------------\n\nVersions include the following system attributes by default. You can modify the values associated\nwith these attributes in Settings. For details, see [Manage attributes](./manage-attributes).\n\nUser-defined attributes\n-----------------------\n\nDepending on your team or organizational needs, you can define custom attributes (name/value pairs)\nfor versions. See [Manage attributes](/apigee/docs/apihub/manage-attributes)."]]