-
Notifications
You must be signed in to change notification settings - Fork 33
Schema for an API Registry
What types and relationships are represented in an API Registry?
All information in a registry is organized under a project, which, in Google-hosted instances, corresponds to a Google Cloud project.
To be consistent with other Google APIs, all resources under a project also have a specified location, which is currently limited to global.
Resource names for projects: projects/{project} (or project/{project}/locations/global as a resource parent)
APIs are top-level entries in an API registry. But what is an API? We started with a relatively narrow definition of APIs (see "Reference API" below), but have come to include many different kinds of APIs in our registries. Here is an open-ended list:
- API reference designs are high-level abstractions that correspond to a relationship between an API producer and its consumers to provide a set of capabilities that can be used in consumer applications. Because these can be long-term relationships, APIs often have multiple versions in various lifecycle stages. In a registry, an API reference design typically describes other kinds of APIs in the registry.
- API hosts are instances that serve an API on a network, usually publicly-available. We might not know much about their implementation and operations; sometimes, all we know about an API is its address, but we register it to note its existence and increase awareness of its status. In many organizations, API hosts are legacy servers and are candidates for improved API management.
- API targets are API servers that are on a secured network that are exposed by a proxy. These typically implement business logic of APIs but leave API management features to proxies.
- API proxies add API runtime management features to an API by bridging connections from clients to target servers.
- API products bundle and wrap API proxies with user management capabilities like developer key generation.
Each of these can be considered to be a "kind" of API and listed in a registry. When we do that, we can also represent the relationships among them.
Resource names for APIs: projects/{project}/locations/global/apis/{api}
A version represents a stable interface that an application developer would use to interact with an API. API versions are abstract (opposed to service implementations, aka deployments, which are concrete). Typically versions have names like ("v1", "v2") or ("1.0", "1.1"). Versions are especially of interest to API consumers, because consumers implement applications to use specific versions of APIs.
Resource names for API versions: projects/{project}/locations/global/apis/{api}/versions/{version}
A spec is a formal description of an API version. A spec may or may not be the primary API definition: some specs are used to implement APIs and others are representations of preexisting APIs. Both kinds of specs can be stored in the registry, meaning that some specs might be derived from others. Specs are stored with revisions, meaning that a history of changes is kept and is available for reference using spec revision IDs. Specs can be of any format. The format of an uploaded spec should be specified in the MIME type field of the spec resource. See Media Types for recommended values.
Resource names for API specs: projects/{project}/locations/global/apis/{api}/versions/{version}/specs/{spec}
A deployment represents a running instance of a service. Deployments are concrete. APIs can have multiple deployments that support different regions of availability, host different versions of the API, or provide different stability levels. Like specs, deployments are stored with revisions, allowing a history of changes to be tracked and referenced.
Resource names for API deployments: projects/{project}/locations/global/apis/{api}/deployments/{deployment}
Artifacts allow registry clients to associate arbitrary information with resources in the registry, allowing flexibility and power to support complex applications. All other resources in the registry can have associated artifacts. This includes projects, APIs, versions, specs, and deployments. Artifacts are stored as blobs of data with associated MIME types stored in the artifact resources. See Media Types for recommended values.
Resource names for artifacts can be any of the following:
projects/{project}/locations/global/artifacts/{artifact}projects/{project}/locations/global/apis/{api}/artifacts/{artifact}projects/{project}/locations/global/apis/{api}/versions/{version}/artifacts/{artifact}projects/{project}/locations/global/apis/{api}/versions/{version}/specs/{spec}/artifacts/{artifact}projects/{project}/locations/global/apis/{api}/deployments/{deployment}/artifacts/{artifact}