This page applies to Apigee and Apigee hybrid.
About API specifications
API specifications use standard formats to describe APIs. They are machine readable, but also easy for humans to read and understand. Specifications typically describe elements of an API such as its base path, paths and verbs, headers, query parameters, operations, content types, response descriptions, and so on, as shown in Figure 1.
Figure 1. Excerpt from an OpenAPI specification.
An API version can contain multiple API specifications of the same or different types such as OpenAPI Spec, Proto, and WSDL. Where supported, API hub can parse an API specification to extract and store API metadata, such as the API ID, version ID, description, and operations. See Specification parsing.
Using API specifications with API hub
You can create an API version in API hub with or without an API specification.
You can upload a specification at the time you create a version. When you view details of an API in the user interface, you will see a list of any specs that are associated with the versions of an API resource.
You can also create and configure a version with a specification using the REST API. When using the API, you create an API version entity with the specification, then you can attach the version to an API resource.
For more information, see Add a spec to a version.
Specification parsing
Where supported, API hub can parse an API specification to extract information about the API and store it with an API version. For example, API hub can parse an API OpenAPI specification to extract and store the API ID, version ID, description, operations, and other metadata.
API hub also supports specification validation. See Validate an API specification.