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 :

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

More detailed information on these is available in the wiki

Pre-requisites

1. Setup your API hub instance

2. gcloud CLI installed

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

   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. Command to activate an existing configuration

    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. We allow export of API from the registry using :

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

2. This will generate a file with following details:

   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: [email protected]
       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 this file a. e.g. add/update deployment information b. Update metadata / labels/ annotations

5. To apply these updates you can run the following command

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

6. To publish an updated specification file to the registry run the command in step 5. a. sourceURI can be a relative path 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.