-
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: 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? While we started with a relatively narrow definition of APIs (see "Reference API" below), we've come to include many different kinds of APIs in our registries. Here is an open-ended list:
- Reference APIs 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, a reference API typically represents a design of an API that specifies and describes other APIs in the registry.
- API servers are instances that serve an API on a network, usually public-available. As standalone entities, we don't know much about their implementation and operations, but sometimes, all we know about an API is its address.
- API targets are API servers that are on a secured network that are exposed by a proxy. These typically implement business logic of APIs.
- 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: 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: 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: 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: 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:
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}