Partial documentation.

cmd/zero/DOCUMENTATION.md

@@ -1,17 +1,18 @@
 # Zero
 
-Simple API management without a gateway. Instead of using a gateway,
-we will make direct calls to service control APIs from within our
-API server.
+Simple API management without a gateway. Instead of using a gateway, we will
+make direct calls to service control APIs from within our API server.
 
-Is this a good idea? 
+Is this a good idea?
 
 Pros:
+
 - simple (no proxies to set up and manage)
 - inexpensive (no additional sidecars to operate)
 - runs anywhere (even when you run your server locally)
 
 Cons:
+
 - requires changes to your application
 - hard to govern, there may be uncontrolled APIs that leak information
 
@@ -25,16 +26,19 @@ To register a service with service manager, a domain is required.
 
 ##### Use a domain you control
 
-We can register a domain with a registrar and prove to Google that we own it, and then we can create services on that domain or any subdomain. “example1.timbx.me”
+We can register a domain with a registrar and prove to Google that we own it,
+and then we can create services on that domain or any subdomain.
+“example1.timbx.me”
 
 ##### Get a domain from App Engine
 
-Alternately, we can use Google App Engine to get a domain that we can use.
-App Engine apps are hosted at <appname>.appspot.com, where <appname> is
-usually the project id.
+Alternately, we can use Google App Engine to get a domain that we can use. App
+Engine apps are hosted at <appname>.appspot.com, where <appname> is usually the
+project id.
 
 - create an app engine app for your project
-- this will give you “appname.appspot.com”. For example, for my project, named “nerdvana”, my domain name is “nerdvana.appspot.com”
+- this will give you “appname.appspot.com”. For example, for my project, named
+  “nerdvana”, my domain name is “nerdvana.appspot.com”
 - we can use this for our service name.
 - we can also use subdomains of this domain.
 
@@ -100,11 +104,10 @@ TODO
 
 ## Using the Service Management API to build an API Catalog
 
-Get a list of managed services and the configurations for each.
-Each configuration includes the list of operations that the API
-supports. These lists can be used to build an index of APIs being
-provided by your Google project.
+Get a list of managed services and the configurations for each. Each
+configuration includes the list of operations that the API supports. These
+lists can be used to build an index of APIs being provided by your Google
+project.
 
-Not all APIs -- these are just the formally registered ones.
-Other indicators of APIs are Load Balancers, Cloud Run endpoints,
-and GKE ingresses.
+Not all APIs -- these are just the formally registered ones. Other indicators
+of APIs are Load Balancers, Cloud Run endpoints, and GKE ingresses.

cmd/zero/cmd/apikeys/cmd.go

@@ -0,0 +1,27 @@
+// Copyright 2023 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.
+
+package apikeys
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func Cmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "api-keys",
+		Short: "API key management",
+	}
+	return cmd
+}

cmd/zero/cmd/apikeys/create.go

@@ -0,0 +1,15 @@
+// Copyright 2023 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.
+
+package apikeys

cmd/zero/cmd/apikeys/delete.go

@@ -0,0 +1,15 @@
+// Copyright 2023 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.
+
+package apikeys

cmd/zero/cmd/apikeys/get.go

@@ -0,0 +1,15 @@
+// Copyright 2023 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.
+
+package apikeys

cmd/zero/cmd/apikeys/list.go

@@ -0,0 +1,15 @@
+// Copyright 2023 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.
+
+package apikeys

cmd/zero/cmd/cmd.go

@@ -17,6 +17,7 @@ package cmd
 import (
 	"context"
 
+	"github.com/apigee/registry-experimental/cmd/zero/cmd/apikeys"
 	"github.com/apigee/registry-experimental/cmd/zero/cmd/petstore"
 	"github.com/apigee/registry-experimental/cmd/zero/cmd/servicecontrol"
 	"github.com/apigee/registry-experimental/cmd/zero/cmd/servicemanagement"
@@ -30,6 +31,7 @@ func Cmd(ctx context.Context) *cobra.Command {
 		Use: "zero",
 	}
 
+	cmd.AddCommand(apikeys.Cmd())
 	cmd.AddCommand(petstore.Cmd())
 	cmd.AddCommand(servicecontrol.Cmd())
 	cmd.AddCommand(servicemanagement.Cmd())

cmd/zero/cmd/petstore/README.md

@@ -1,11 +1,95 @@
+# petstore
 
+This directory contains subcommands that provide a demonstration API server
+that uses Service Control to check and log API requests.
 
+## Create credentials.
+
+To run the example, we'll need to call several Google APIs, and we'll
+authenticate our calls using a service account. Create a service account in the
+Cloud Console and download a JSON key. Move this file to
+`~/.config/zero/control.json`.
+
+The service account needs the following roles:
+
+- Service Management Administrator, to register and configure our service
+- Service Controller, to make calls to the Service Control API
+- API Keys Admin, to create and manage API keys
+
+## Register the service.
+
+Next we will use the Service Management API to create a "managed service". This
+is a top-level entity that we'll use to track service descriptions, access
+controls, and logs.
+
+The Service Management API requires that service names be domains or subdomains
+that are known to belong to us. That is because Service Infrastructure is often
+used to manage services that Google hosts. If we're only using Service Control
+that's not the case: Google is not hosting our service, but the requirement is
+still enforced.
+
+To use a domain that we own as our service name, we can prove our ownership by
+following the instructions
+[here](https://cloud.google.com/endpoints/docs/openapi/verify-domain-name).
+Once we've verified ownership, we can use our verified domain name or any
+subdomain as a service name.
+
+A simpler alternative is to instead use a domain name that Google controls and
+delegates to us. As described
+[here](https://cloud.google.com/endpoints/docs/openapi/configure-endpoints#use_a_domain_managed_by_google),
+these can be `*projectname*.appspot.com` or any subdomain of
+`endpoints.*projectname*.cloud.goog`. Subdomains of `*projectname*.appspot.com`
+are also ok, so if we had a project named `nerdvana`, we might create a service
+named `petstore.nerdvana.appspot.com`.
+
+Again, when we're only using Service Control, this name is just an identifier
+and doesn't need to match the hostname of our service.
+
+We can create the service using our CLI.
+
+```
 zero service-management services create petstore.nerdvana.appspot.com --project nerdvana
+```
+
+## Generate the Service Configuration.
+
+We describe our service to Service Infrastructure using a structure called
+Service Config. Service Config can be generated by tools that read API
+descriptions from various formats, but for our example, we will generate the
+Service Config directly with code in our CLI.
+
+We can run the following to view the Service Config:
+
+```
+zero petstore config petstore.nerdvana.appspot.com
+```
+
+We can apply it by adding the `--apply` and `--project` flags.
+
+```
 zero petstore config petstore.nerdvana.appspot.com --project nerdvana
-zero service-management services rollouts create petstore.nerdvana.appspot.com 2023-10-07r0
+```
 
+Note the contents of the `id` field in the result. We'll need that to roll out
+our configuration.
 
+## Roll out the service configuration.
 
+```
+zero service-management services rollouts create petstore.nerdvana.appspot.com 2023-10-12r0
+```
+
+Note that this is a long-running operation. We can check its status in the
+Cloud Console.
+
+## Generate an API key.
+
+## Run the server and make requests.
+
+```
 ab -n 50 -c 10 -H "X-Api-Key: $APIKEY" http://localhost:8080/v1/pets
 ab -n 50 -c 10 -H "X-Api-Key: $APIKEY" http://localhost:8080/v1/pets/1
 ab -n 50 -c 10 -H "X-Api-Key: $APIKEY" -p pet.json -T application/json http://localhost:8080/v1/pets
+```
+
+## View the results in the Endpoints console.