The Registry Tool Quickstart

The registry tool is a command-line tool for working with API registries based on the Registry API.

More details about the tool are available here.

You can use the registry tool to create and manage the following :

• APIs
• API Versions
• API Specs and their revisions
• API Deployments and their revisions
• Artifacts

More detailed information on these is available in Schema for an API Registry

The registry tool can be used with standalone instances of the Registry server or with hosted instances like Google's Apigee Registry API, which is included as part of Apigee API hub.

Prerequisites

1. Set up your API hub instance or your local instance of the Registry API server.
2. If you are using a local instance, install gcloud.
3. Download the registry tool from https://github.com/apigee/registry/releases for your operating system.

MacOS note: To run a downloaded registry tool on MacOS, you may need to unquarantine it by running the following on the command line:

xattr -d com.apple.quarantine registry

Getting Started

1. Create a configuration for your registry project. For hosted instances:

   registry config configurations create config-<gcp-project-name> \
       --registry.address=apigeeregistry.googleapis.com:443 \
       --registry.insecure=0 \
       --registry.project=<gcp-project-name> \
       --registry.location=global
   

2. Your configuration will be automatically activated. You can switch between configurations with:

    registry config configurations activate <config-name>
   

3. The registry tool needs to generate tokens to authenticate. Note: Please ensure the gcloud has been initialized using gcloud auth login

   registry config set token-source 'gcloud auth print-access-token'
   

4. The following commands will list the entries in your API registry

   # List all apis
   registry get apis
   
   # List versions of all apis
   registry get apis/-/versions
   
   # List all specs
   registry get apis/-/versions/-/specs
   
   # List all deployments
   registry get apis/-/deployments
   
   

5. The following commands will return details of a specific entry

   # get details of a specific api entry
   registry get apis/openapi-sample -o yaml
   
   # get details of a specific version entry
   registry get apis/openapi-sample/versions/v1 -o yaml
   
   # get details of a specific version
   registry get apis/openapi-sample/versions/v1/specs/petstore.json -o yaml
   
   # get the contents of a spec
   registry get apis/openapi-sample/versions/v1/specs/petstore.json -o contents
   
   # get details of a deployment
   registry get apis/openapi-sample/deployments/sample -o yaml
   

Managing API information in the registry

Often teams will want to manage / update API information in the registry using CI/CD pipelines.

1. API information can be exported from the registry using registry get.

   registry get apis/openapi-sample > openapi-sample.yaml
   
   

2. This will generate a file with contents like the following:

   apiVersion: apigeeregistry/v1
   kind: API
   metadata:
     name: openapi-sample
     labels:
       apihub-lifecycle: concept
       apihub-style: apihub-openapi
       apihub-target-users: public
     annotations:
       apihub-primary-contact: openapi-team@example.com
       apihub-primary-contact-description: OpenAPI Team
   data:
     displayName: OpenAPI Example
     description: Sample OpenAPI specification
     versions:
       - metadata:
           name: v1
           annotations:
             apihub-end-of-life-type: apihub-unknown
         data:
           displayName: v1
           state: concept
           specs:
             - metadata:
                 name: petstore.json
                 annotations:
                   apihub-comment: Initial version
               data:
                 filename: petstore.json
                 mimeType: application/x.openapi+gzip
                 sourceURI: https://petstore.swagger.io/v2/swagger.json
     deployments:
       - metadata:
           name: sample
           labels:
             apihub-gateway: apihub-google-cloud-apigee
           annotations:
             apihub-external-channel-name: View Documentation
         data:
           displayName: sample
           apiSpecRevision: v1/specs/petstore.json
           externalChannelURI: http://swagger-ui-endpoint/render/projects/project1/locations/global/apis/openapi-sample/deployments/sample
           accessGuidance: |
             <a href="http://google.com">Google website</a>
     artifacts:
       - kind: ReferenceList
         metadata:
           name: apihub-dependencies
         data:
           displayName: ""
           description: Defines a list of dependencies
           references: []
       - kind: ReferenceList
         metadata:
   

3. API Teams can maintain these files in their source control repositories.

4. Teams can make changes to these files a. e.g. add/update deployment information b. Update metadata including labels and annotations

5. Updates can be applied to the registry with registry apply:

   registry apply -f openapi-sample.yaml --parent=projects/PROJECT/locations/global
   

6. registry apply can also be used to update a spec to the registry. sourceURI can be a relative path to the spec file, e.g file://specs/petstore-v1.yaml

Using Cloud Build to publish API information to registry

This repository https://github.com/giteshk/registry-cloudbuild-sample contains a sample of how to use Cloud Build to deploy API information to the registry.