Skip to content

Registry YAML

Jump to bottom
Tim Burks edited this page Feb 21, 2023 · 4 revisions

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.

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

apiVersion

This top-level field should be first and should always contain apigeeregistry/v1.

kind

This top-level field identifies the type of object. Possible values include API, Version, Spec, Deployment, or the name of any artifact type.

metadata

This section includes general information common to all registry resources.

name

This is a unique identifier for the resource, also known as an AIP-122 resource ID.

parent

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.

labels and annotations

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.

data

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.

Example Registry YAML

Top-level resource

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.

Child resource

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.

Resource nesting

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.

Resource collections

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.

Importing API specs with Registry YAML

For many 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.

A Recommended Directory Structure for Exported Registries

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 echoes index.html from the web
  • catalog.yaml, which is used by Backstage
  • api.yaml, version.yaml, etc. which seem tedious to differentiate and maintain. Also spec.yaml might be confused with an actual API spec.
  • <resourceid>.yaml which duplicates the name of the directory containing the resource. For specs, this might also collide with the filename of an API spec.
Clone this wiki locally