Representing FieldSets

FieldSet artifacts allow groups of values to be stored in a registry and displayed in user interfaces like API Hub and the Registry Viewer.

FieldSet artifacts are defined in fields.proto. FieldSet artifacts can be associated with any resource (project, api, version, spec, or deployment) and are generally for storing raw values only. Contents of FieldSets are described in FieldSetDefinition artifacts, also described in fields.proto. FieldSetDefinition artifacts are typically stored at the project level.

Here is a sample FieldSet, described with Registry YAML. It is associated with an API named apis/acme.com and can be added to the registry with registry apply -f support.yaml. Note that PROJECTID below needs to be the id of the project where the API is stored. We recommend that FieldSet YAML be stored in files matching their artifact name in a directory associated with their parent API. Here we use support.yaml for the support artifact).

apiVersion: apigeeregistry/v1
kind: FieldSet
metadata:
  parent: apis/APIID
  name: support
data:
  definitionName: projects/PROJECTID/locations/global/artifacts/support
  values:
    email: "[email protected]"
    team: "Team"

The definitionName in the above FieldSet refers to a FieldSetDefinition that describes the contents of the FieldSet and how it should be displayed. It can be added as a project-level artifact with `registry apply -f supportdefinition.yaml:

apiVersion: apigeeregistry/v1
kind: FieldSetDefinition
metadata:
  name: support
data:
  displayName: Support
  description: Look here to find support for this API.
  fields:
    - id: team
      displayName: Team
      description: Team that owns the API
    - id: email
      displayName: Support Email
      description: Contact the API support team for this API

Example script

Here's a small bash script that shows how these can be set with the registry tool:

#!/bin/bash
# This script illustrates a way to use the registry tool
# to set a custom field set on an API.

# Your registry project ID.
# If PROJECT_ID is unspecified, use a default value.
PROJECT_ID=${PROJECT_ID:-catalog}

# The ID of the API we want to annotate.
# If API_ID is unspecified, use a default value.
API_ID=${API_ID:-adafruit.com}

# Please be sure that the registry tool is configured to point to your project.
# The following configuration is for Google-hosted registries.
registry config set address apigeeregistry.googleapis.com:443
registry config set insecure false
registry config set location global

# Configure the registry tool to use your project.
registry config set project ${PROJECT_ID}

# Apply the FieldSetDefinition. This only needs to be
# done once for all APIs that use this definition.
registry apply -f - <<EOF
apiVersion: apigeeregistry/v1
kind: FieldSetDefinition
metadata:
  name: support
data:
  displayName: Support Information
  description: Look here to find support for this API.
  fields:
    - id: team
      displayName: Team
      description: Team that owns the API
    - id: email
      displayName: Support Email
      description: Contact the API support team for this API
EOF

# Apply the FieldSet. This contains the specific values associated
# with its parent. The parent field is a resource name relative
# to the configured project. "apis/API_ID" is equivalent to
# "projects/PROJECT_ID/locations/global/apis/API_ID".
registry apply -f - <<EOF
apiVersion: apigeeregistry/v1
kind: FieldSet
metadata:
  parent: apis/${API_ID}
  name: support
data:
  definitionName: projects/${PROJECT_ID}/locations/global/artifacts/support
  values:
    email: "[email protected]"
    team: "API Makers"
EOF

Save this to a file named fieldset.sh and apply it with the following:

# This sets the API_ID and PROJECT_ID from the command-line before running the script.
# Alternately, you could just edit them in the `fieldset.sh` script.
API_ID=adafruit.com PROJECT_ID=registry-eval bash ./fieldset.sh 

Now your field set is ready for display. In API Hub, it will be on the right side of the screen like this: