-
Notifications
You must be signed in to change notification settings - Fork 33
Registry YAML
Following the patterns used in Kubernetes Objects, here we define a YAML format that describes resources along with metadata that identifies the type of information and its place in the registry.
The general structure is illustrated below and implemented in pkg/encoding.
apiVersion: apigeeregistry/v1
kind: <kind>
metadata:
name: <resource id>
parent: <project-local parent name, if needed>
labels:
<name1>: <value1>
<name2>: <value2>
annotations:
<name1>: <value1>
<name2>: <value2>
data:
// resource-specific fields
This top-level field should be first and should always contain apigeeregistry/v1.
This top-level field identifies the type of object. Possible values include API, Version, Spec, Deployment, or the name of any artifact type.
This section includes general information common to all registry resources.
This is a unique identifier for the resource, also known as an AIP-122 resource ID.
This uniquely identifies the parent of the resource, with the containing project and location removed. These are removed for conciseness and to allow Registry YAML files to easily be imported into multiple projects or moved from project-to-project.
For top-level resources (APIs and project-level artifacts), the parent field should be omitted or left blank. For other resources, this should be the project-local path of its parent. For example, an artifact associated with an API with id registry would have parent apis/registry and an artifact associated with an API spec might have parent apis/registry/versions/v1/specs/openapi.
These key-value pairs describe labels and annotations that are associated with registry resources. These follow Google Cloud (1) (2) and Kubernetes (3) (4) conventions.
The data section contains resource-specific fields. Kubernetes users might expect this section to be named spec. But in Kubernetes, spec describes desired state (as most Kubernetes inputs do). Here we are describing the actual state of the registry immediately after this resource is applied. This more closely corresponds to Kubernetes ConfigMaps, which use data to name a similar section.
Top-level resources are applied using the kind, metadata.name, and data fields.
apiVersion: apigeeregistry/v1
kind: API
metadata:
name: my-api
data:
displayName: My API
description: Description of my API.
The metadata.parent field specifies the project-local path of the resource's parent. Top-level resources like APIs or project artifacts should omit the metadata.parent field or leave it blank.
apiVersion: apigeeregistry/v1
kind: Deployment
metadata:
name: my-deployment
parent: apis/my-api
data:
displayName: My Deployment
description: Description of my deployment.
Child resources can be nested as part of their parent resource's data field.
apiVersion: apigeeregistry/v1
kind: API
metadata:
name: my-api
data:
displayName: My API
description: Description of my API.
versions:
- metadata:
name: v1
data:
displayName: v1
description: Description of my first API Version.
- metadata:
name: v2
data:
displayName: v2
description: Description of my second API Version.
Collections of resources can be specified using the items list field.
apiVersion: apigeeregistry/v1
items:
- apiVersion: apigeeregistry/v1
kind: API
metadata:
name: my-api
data:
displayName: My API
description: Description of my API.
- apiVersion: apigeeregistry/v1
kind: MyCustomArtifact
metadata:
name: my-artifact
data:
displayName: My Artifact
description: Description of my artifact.
For a number of reasons, we think it is important to maintain API specs in separate files and not include them inline in Registry YAML files. To import them with Registry YAML, registry apply uses the filename field of specs to identify the files to upload and it looks for these files in the same directory where the referring YAML file is found. If no file is found, registry apply attempts to read the spec from the URI in the sourceURI field.
Registry YAML representations are fully self-contained. They can be applied using their contents only; file names and pathnames can be arbitrary. This allows an individual YAML file to be generated by a tool or accessory and directly applied.
However, for ease of use, we recommend that collections of YAML files be organized in a structured way that reflects the registry structure. Here is an example:
my-project/
artifacts/
styleguide.yaml
apis/
registry/
info.yaml
versions/
v1/
info.yaml
specs/
discovery/
info.yaml
discovery.json
artifacts/
apihub-conformance.yaml
apihub-score.yaml
complexity.yaml
vocabulary.yaml
deployments/
prod/
info.yaml
artifacts/
apihub-related.yaml
Note that the structure is generally an alternating sequence of resource ids and collection names, with leaf-level entries being YAML files. Resources that can have child resources are represented with directories that use the resource id as their name. These directories contain a special file info.yaml that describes the resource itself (e.g. my-project/apis/registry/info.yaml is an API description). Since artifacts don’t have child resources, they are directly stored in YAML files using the artifact id and the .yaml extension.
As mentioned earlier, this structure is purely an organizational convenience. The registry tool applies each file using its contents only, so files could be in any structure that users prefer. It is likely, however, that we would export registries into this structure.
info.yaml is an arbitrary choice, but seems the best of alternatives that include:
-
index.yaml, which echoesindex.htmlfrom the web -
catalog.yaml, which is used by Backstage -
api.yaml,version.yaml, etc. which seem tedious to differentiate and maintain. Alsospec.yamlmight be confused with an actual API spec. -
<resourceid>.yamlwhich duplicates the name of the directory containing the resource. For specs, this might also collide with the filename of an API spec.