Simplify demo and walkthrough scripts, replace references to apg wi…

…th `registry rpc` calls (#577)

* Replace references to `apg` with `registry rpc` calls.
* Fix small problems in walkthrough.sh
* Update demos/README.md with info about setup-project.sh
* Add --force flag to registry project deletion
* Reduce demo scripts to basic API management.

demos/README.md

@@ -11,3 +11,13 @@ Registry API.
 - [protos.sh](protos.sh) builds and analyzes a collection of APIs described by
   Protocol Buffer files distributed with the
   [googleapis](https://github.com/googleapis/googleapis) repo.
+
+These scripts expect that the `PROJECT` is set to the id of the registry
+project. For self-hosted (open source) installations, you can set this variable
+by sourcing [setup-project.sh](setup-project.sh) as follows:
+
+```
+. setup-project.sh
+```
+
+This creates a project named `sample`.

demos/disco.sh

@@ -27,14 +27,7 @@
 # server, run `. auth/LOCAL.sh` in the shell before running the following
 # commands.
 
-# A registry exists under a top-level project.
-PROJECT=disco
-
-# First, delete and re-create the "disco" project to get a fresh start.
-apg admin delete-project --name projects/$PROJECT
-apg admin create-project --project_id $PROJECT \
-	--project.display_name "Discovery" \
-	--project.description "Descriptions of public Google APIs from the API Discovery Service"
+# This script assumes that PROJECT is set to the name of your registry project.
 
 # Upload all of the APIs from the Discovery Service at once.
 # This happens in parallel and usually takes a minute or two.
@@ -59,68 +52,20 @@ registry list projects/$PROJECT/locations/global/apis/-/versions/-/specs
 # To see more about an individual spec, use the `registry get` command:
 registry get projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/discovery.json
 
-# You can also get this with the automatically-generated `apg` command line tool:
-apg registry get-api-spec \
+# You can also get this with direct calls to the registry rpc service:
+registry rpc get-api-spec \
 	--name projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/discovery.json
 
 # Add the `--json` flag to get this as JSON:
-apg registry get-api-spec --json \
+registry rpc get-api-spec --json \
 	--name projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/discovery.json
 
 # You might notice that that didn't return the actual spec. That's because the spec contents
 # are accessed through a separate method that (when transcoded to HTTP) allows direct download
 # of spec contents.
-apg registry get-api-spec-contents \
+registry rpc get-api-spec-contents \
 	--name projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/discovery.json
 
 # Another way to get the bytes of the spec is to use `registry get` with the `--contents` flag.
 registry get projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/discovery.json \
 	--contents
-
-# The registry tool can compute simple complexity metrics for Discovery documents stored in the Registry.
-registry compute complexity projects/$PROJECT/locations/global/apis/-/versions/-/specs/-
-
-# Complexity results are stored in artifacts associated with the specs.
-registry list projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/complexity
-
-# We can use the `registry get` subcommand to read individual complexity records.
-registry get projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/discovery.json/artifacts/complexity
-
-# The registry tool also supports exporting all of the complexity results to a Google sheet.
-# (The following command expects OAuth client credentials with access to the
-# Google Sheets API to be available locally in ~/.credentials/registry.json)
-registry export sheet projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/complexity \
-	--as projects/$PROJECT/locations/global/artifacts/complexity-sheet
-
-# We can also compute the vocabulary of APIs described with Discovery documents.
-registry compute vocabulary projects/$PROJECT/locations/global/apis/-/versions/-/specs/-
-
-# Vocabularies are also stored as artifacts associated with API specs.
-registry get projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/discovery.json/artifacts/vocabulary
-
-# The registry command can perform set operations on vocabularies.
-# To find common terms in all Google speech-related APIs, use the following:
-registry vocabulary intersection projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/vocabulary \
-	--filter "api_id.contains('speech')"
-
-# We can also save this to a property.
-registry vocabulary intersection projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/vocabulary \
-	--filter "api_id.contains('speech')" --output projects/$PROJECT/locations/global/artifacts/speech-common
-
-# We can then read it directly or export it to a Google Sheet.
-registry get projects/$PROJECT/locations/global/artifacts/speech-common --contents
-registry export sheet projects/$PROJECT/locations/global/artifacts/speech-common
-
-# To see a larger vocabulary, let's now compute the union of all the vocabularies in our project.
-registry vocabulary union projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/vocabulary \
-	--output projects/$PROJECT/locations/global/artifacts/vocabulary
-
-# We can also export this with `registry get` but it's easier to view this as a sheet:
-registry export sheet projects/$PROJECT/locations/global/artifacts/vocabulary
-
-# You'll notice that usage counts are included for each term, so we can sort by count
-# and find the most commonly-used terms across all of our APIs.
-# With vocabulary operations we can discover common terms across groups of APIs,
-# track changes across versions, and find unique terms in APIs that we are reviewing.
-# By storing these results and other artifacts in the Registry, we can build a
-# centralized store of API information that can help manage an API program.

demos/openapi.sh

@@ -27,14 +27,7 @@
 # server, run `. auth/LOCAL.sh` in the shell before running the following
 # commands.
 
-# A registry exists under a top-level project.
-PROJECT=openapi
-
-# First, delete and re-create the "openapis" project to get a fresh start.
-apg admin delete-project --name projects/$PROJECT
-apg admin create-project --project_id $PROJECT \
-	--project.display_name "OpenAPI Directory" \
-	--project.description "APIs collected from the APIs.guru OpenAPI Directory"
+# This script assumes that PROJECT is set to the name of your registry project.
 
 # Get the commit hash of the checked-out OpenAPI directory
 export COMMIT=`(cd ~/Desktop/openapi-directory; git rev-parse HEAD)`
@@ -48,20 +41,20 @@ registry upload bulk openapi \
 # Get one of the APIs.
 registry get projects/$PROJECT/locations/global/apis/wordnik.com
 
-# You can also get this API with the lower-level apg command.
+# You can also get this API with direct calls to the registry rpc service.
 # Add the --json option to get JSON-formatted output.
-apg registry get-api --name projects/$PROJECT/locations/global/apis/wordnik.com --json
+registry rpc get-api --name projects/$PROJECT/locations/global/apis/wordnik.com --json
 
 # Get the API spec
-apg registry get-api-spec --name projects/$PROJECT/locations/global/apis/wordnik.com/versions/4.0/specs/openapi.yaml
+registry rpc get-api-spec --name projects/$PROJECT/locations/global/apis/wordnik.com/versions/4.0/specs/openapi.yaml
 
 # You might notice that that didn't return the actual spec. That's because the spec contents
 # are accessed through a separate method that (when transcoded to HTTP) allows direct download
 # of spec contents.
-apg registry get-api-spec-contents --name projects/$PROJECT/locations/global/apis/wordnik.com/versions/4.0/specs/openapi.yaml
+registry rpc get-api-spec-contents --name projects/$PROJECT/locations/global/apis/wordnik.com/versions/4.0/specs/openapi.yaml
 
 # If you have jq and the base64 tool installed, you can get the spec contents from the RPC response.
-# apg registry get-api-spec-contents --name projects/$PROJECT/locations/global/apis/wordnik.com/versions/4.0/specs/openapi.yaml --json | jq .data -r | base64 --decode
+# registry rpc get-api-spec-contents --name projects/$PROJECT/locations/global/apis/wordnik.com/versions/4.0/specs/openapi.yaml --json | jq .data -r | base64 --decode
 
 # Another way to get the bytes of the spec is to use `registry get` with the `--contents` flag.
 registry get projects/$PROJECT/locations/global/apis/wordnik.com --contents
@@ -97,44 +90,3 @@ registry list projects/$PROJECT/locations/global/apis/-/versions/-/specs/- \
 # This is a bit more verbose than glob expressions but much more powerful.
 # You can also refer to other fields in the messages that match the pattern:
 registry list projects/$PROJECT/locations/global/apis/- --filter "description.contains('speech')"
-
-# The registry command can also compute some basic API properties.
-# This computes simple complexity metrics for every spec in the project.
-registry compute complexity projects/$PROJECT/locations/global/apis/-/versions/-/specs/-
-
-# The complexity metrics are stored in artifacts associated with each spec.
-# In this case, the artifacts were stored in a serialized protocol buffer.
-# You can get their values with the "get" subcommand.
-registry get projects/$PROJECT/locations/global/apis/wordnik.com/versions/4.0/specs/openapi.yaml/artifacts/complexity --contents
-
-# It's also possible to export artifacts to a Google sheet.
-# (The following command expects OAuth client credentials with access to the
-# Google Sheets API to be available locally in ~/.credentials/registry.json)
-registry export sheet projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/complexity \
-	--as projects/$PROJECT/locations/global/artifacts/complexity-sheet
-
-# Another interesting property that can be computed is the "vocabulary" of an API.
-# The following command computes vocabularies of every API spec in the project.
-registry compute vocabulary projects/$PROJECT/locations/global/apis/-/versions/-/specs/-
-
-# Vocabularies are stored in the "vocabulary" property.
-registry get projects/$PROJECT/locations/global/apis/wordnik.com/versions/4.0/specs/openapi.yaml/artifacts/vocabulary --contents
-
-# The registry command can perform set operations on vocabularies.
-# To find common terms in all Google APIs, use the following:
-registry vocabulary intersection projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/vocabulary \
-  --filter "api_id.startsWith('googleapis')"
-
-# We can also save this to a property.
-registry vocabulary intersection projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/vocabulary \
-  --filter "api_id.startsWith('googleapis')" \
-  --output projects/$PROJECT/locations/global/artifacts/google-common
-
-# We can then read it directly or export it to a Google Sheet.
-registry get projects/$PROJECT/locations/global/artifacts/google-common
-registry export sheet projects/$PROJECT/locations/global/artifacts/google-common
-
-# With vocabulary operations we can discover common terms across groups of APIs,
-# track changes across versions, and find unique terms in APIs that we are reviewing.
-# By storing these results and other artifacts in the Registry, we can build a
-# centralized store of API information that can help manage an API program.

demos/protos.sh

@@ -28,14 +28,7 @@
 # server, run `. auth/LOCAL.sh` in the shell before running the following
 # commands.
 
-# A registry exists under a top-level project.
-PROJECT=protos
-
-# First, delete and re-create the project to get a fresh start.
-apg admin delete-project --name projects/$PROJECT
-apg admin create-project --project_id $PROJECT \
-	--project.display_name "Google APIs" \
-	--project.description "Protocol buffer descriptions of public Google APIs"
+# This script assumes that PROJECT is set to the name of your registry project.
 
 # Get the commit hash of the checked-out protos directory
 export COMMIT=`(cd ~/Desktop/googleapis; git rev-parse HEAD)`
@@ -65,77 +58,23 @@ registry list projects/$PROJECT/locations/global/apis/-/versions/-/specs
 # To see more about an individual spec, use the `registry get` command:
 registry get projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/google-cloud-translate-v3.zip
 
-# You can also get this with the automatically-generated `apg` command line tool:
-apg registry get-api-spec --name projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/google-cloud-translate-v3.zip
+# You can also get this with direct calls to the registry rpc service:
+registry rpc get-api-spec --name projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/google-cloud-translate-v3.zip
 
 # Add the `--json` flag to get this as JSON:
-apg registry get-api-spec --name projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/google-cloud-translate-v3.zip --json
+registry rpc get-api-spec --name projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/google-cloud-translate-v3.zip --json
 
 # You might notice that that didn't return the actual spec. That's because the spec contents
 # are accessed through a separate method that (when transcoded to HTTP) allows direct download
 # of spec contents.
-apg registry get-api-spec-contents --name projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/google-cloud-translate-v3.zip
+registry rpc get-api-spec-contents --name projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/google-cloud-translate-v3.zip > protos-1.zip
 
 # An easier way to get the bytes of the spec is to use `registry get` with the `--contents` flag.
 # This writes the bytes to stdout, so you probably want to redirect this to a file, as follows:
 registry get projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/google-cloud-translate-v3.zip \
-	--contents > protos.zip
+	--contents > protos-2.zip
 
 # When you unzip this file, you'll find a directory hierarchy suitable for compiling with `protoc`.
 # protoc google/cloud/translate/v3/translation_service.proto -o.
 # (This requires additional protos that you can find in
 # [github.com/googleapis/api-common-protos](https://github.com/googleapis/api-common-protos).
-
-# The registry tool can compute simple complexity metrics for protos stored in the Registry.
-registry compute complexity projects/$PROJECT/locations/global/apis/-/versions/-/specs/-
-
-# Complexity results are stored in artifacts associated with the specs.
-registry list projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/complexity
-
-# We can use the `registry get` subcommand to read individual complexity records.
-registry get projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/google-cloud-translate-v3.zip/artifacts/complexity
-
-# The registry tool also supports exporting all of the complexity results to a Google sheet.
-# (The following command expects OAuth client credentials with access to the
-# Google Sheets API to be available locally in ~/.credentials/registry.json)
-registry export sheet projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/complexity \
-	--as projects/$PROJECT/locations/global/artifacts/complexity-sheet
-
-# We can also compute the vocabulary of proto APIs.
-registry compute vocabulary projects/$PROJECT/locations/global/apis/-/versions/-/specs/-
-
-# Vocabularies are also stored as artifacts associated with API specs.
-registry get projects/$PROJECT/locations/global/apis/translate/versions/v3/specs/google-cloud-translate-v3.zip/artifacts/vocabulary
-
-# The registry command can perform set operations on vocabularies.
-# To find common terms in all Google speech-related APIs, use the following:
-registry vocabulary intersection projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/vocabulary \
-	--filter "api_id.contains('speech')"
-
-# We can also save this to a property.
-registry vocabulary intersection projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/vocabulary \
-	--filter "api_id.contains('speech')" --output projects/$PROJECT/locations/global/artifacts/speech-common
-
-# We can then read it directly or export it to a Google Sheet.
-registry get projects/$PROJECT/locations/global/artifacts/speech-common
-registry export sheet projects/$PROJECT/locations/global/artifacts/speech-common
-
-# To see a larger vocabulary, let's now compute the union of all the vocabularies in our project.
-registry vocabulary union projects/$PROJECT/locations/global/apis/-/versions/-/specs/-/artifacts/vocabulary \
-	--output projects/$PROJECT/locations/global/artifacts/vocabulary
-
-# We can also export this with `registry get` but it's easier to view this as a sheet:
-registry export sheet projects/$PROJECT/locations/global/artifacts/vocabulary
-
-# You'll notice that usage counts are included for each term, so we can sort by count
-# and find the most commonly-used terms across all of our APIs.
-# With vocabulary operations we can discover common terms across groups of APIs,
-# track changes across versions, and find unique terms in APIs that we are reviewing.
-# By storing these results and other artifacts in the Registry, we can build a
-# centralized store of API information that can help manage an API program.
-
-# We can also run analysis tools like linters and store the results in the Registry.
-# Here we run the Google api-linter and compile summary statistics.
-registry compute lint projects/$PROJECT/locations/global/apis/-/versions/-/specs/-
-registry compute lintstats projects/$PROJECT/locations/global/apis/-/versions/-/specs/- --linter aip
-registry compute lintstats projects/$PROJECT --linter aip

demos/setup-project.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+#
+# Copyright 2022 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# A registry exists under a top-level project.
+# Set the PROJECT environment variable to the name of your project.
+PROJECT=sample
+
+# Self-hosted (open source) installations require project creation.
+
+# Delete and re-create the project to get a fresh start.
+registry rpc admin delete-project --name projects/$PROJECT --force
+registry rpc admin create-project --project_id $PROJECT \
+	--project.display_name $PROJECT \
+	--project.description "A registry project"
+