README
¶
Registry API Core Implementation
This repository contains the core implementation of the Registry API. Please see the wiki for more information.
The Registry API
The Registry API allows teams to upload and share machine-readable descriptions of APIs that are in use and in development. These descriptions include API specifications in standard formats like OpenAPI, the Google API Discovery Service Format, and the Protocol Buffers Language. These API specifications can be used by tools like linters, browsers, documentation generators, test runners, proxies, and API client and server generators. The Registry API itself can be seen as a machine-readable enterprise API catalog designed to back online directories, portals, and workflow managers.
The Registry API is formally described by the Protocol Buffer source files in google/cloud/apigeeregistry/v1. It closely follows the Google API Design Guidelines at aip.dev and presents a developer experience consistent with production Google APIs. Please tell us about your experience if you use it.
The Registry Tool
The Registry Tool (registry) is a command-line tool that simplifies setup and
operation of a registry. See cmd/registry and
the Registry wiki for more
information. The registry tool can be built from sources here or installed
with this script on Linux or Darwin:
curl -L https://raw.githubusercontent.com/apigee/registry/main/downloadLatest.sh | sh -
This Implementation
This implementation is a gRPC service written in Go. It can be run locally or deployed in a container using services including Google Cloud Run. It stores data using a configurable relational interface layer that currently supports PostgreSQL and SQLite.
The Registry API service is annotated to support gRPC HTTP/JSON transcoding, which allows it to be automatically published as a JSON REST API using a proxy. Proxies also enable gRPC web, which allows gRPC calls to be directly made from browser-based applications. A configuration for the Envoy proxy is included (deployments/envoy/envoy.yaml).
The Registry API protos also include configuration to support generated API clients (GAPICS), which allow idiomatic API usage from a variety of languages. A Go GAPIC library is generated as part of the build process using gapic-generator-go.
A command-line interface is in cmd/registry and provides a mixture of hand-written high-level features and automatically generated subcommands that call individual RPC methods of the Registry API.
The entry point for the Registry API server itself is cmd/registry-server. For more on running the server, see cmd/registry-server/README.md.
Build Instructions
The following tools are needed to build this software:
- Go 1.18 (recommended) or later.
- protoc, the Protocol Buffer Compiler (see tools/PROTOC-VERSION.sh for the currently-used version).
- make, git, and other elements of common unix build environments.
This repository contains a Makefile that downloads all other
dependencies and builds this software (make all). With dependencies
downloaded, subsequent builds can be made with go install ./... or
make lite.
Quickstart
The easiest way to try the Registry API is to run registry-server locally. By
default, the server is configured to use a SQLite database.
registry-server
Next, in a separate terminal, configure your environment to point to this server with the following:
. auth/LOCAL.sh
Now you can check your server and configuration with the registry tool:
registry rpc admin get-status
Next run a suite of tests with make test and see a corresponding walkthrough
of API features in tests/demo/walkthrough.sh. For
more demonstrations, see the demos directory.
Tests
This repository includes tests that verify registry-server. These server tests
focus on correctness at the API level and compliance with the API design
guidelines described at aip.dev. Server tests are included in
runs of make test and go test ./..., and the server tests can be run by
themselves with go test ./server/registry. By default, server tests verify the
local code in ./server/registry, but to allow API conformance testing, the
tests can be run to verify remote servers using the following options:
- With the
-remoteflag, tests are run against a remote server according to the configuration used by theregistrytool. This runs the entire suite of tests. WARNING: These tests are destructive and will overwrite everything in the remote server. - With the
-hosted PROJECT_IDflag, tests are run against a remote server in a hosted environment within a single project that is expected to already exist. The server is identified and authenticated with the configuration used by theregistrytool. Only the methods of the Registry service are tested (Admin service methods are excluded). WARNING: These tests are destructive and will overwrite everything in the specified project.
A small set of performance benchmarks is in
tests/benchmark. These tests run against remote servers
specified by the registry tool configuration and test a single project that is
expected to already exist. WARNING: These tests are destructive and will
overwrite everything in the specified project. Benchmarks can be run with the
following invocation:
go test ./tests/benchmark --bench=. --project_id=$PROJECTID --benchtime=${ITERATIONS}x --timeout=0
All of the test configurations described above are verified in this repository's CI tests.
License
This software is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.
Disclaimer
This is not an official Google product. Issues filed on GitHub are not subject to service level agreements (SLAs) and responses should be assumed to be on an ad-hoc volunteer basis.
Contributing
Contributions are welcome! Please see CONTRIBUTING for notes on how to contribute to this project.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
registry/cmd/check/rules
Package rules contains implementations of checker rules.
|
Package rules contains implementations of checker rules. |
|
registry/cmd/check/rules/rule100
Api availability field is free-form, but we expect single words that describe availability.
|
Api availability field is free-form, but we expect single words that describe availability. |
|
registry/cmd/check/rules/rule1001
if label name is the same as a Taxonomy name, its value must match one of the Taxonomy's Element's ID
|
if label name is the same as a Taxonomy name, its value must match one of the Taxonomy's Element's ID |
|
registry/cmd/check/rules/rule1003
APIVersion state must match a valid lifecycle stage
|
APIVersion state must match a valid lifecycle stage |
|
registry/cmd/check/rules/rule101
Api recommended_version must be an ApiVersion that is a child of this Api.
|
Api recommended_version must be an ApiVersion that is a child of this Api. |
|
registry/cmd/check/rules/rule102
Api recommended_version must be an ApiVersion that is a child of this Api.
|
Api recommended_version must be an ApiVersion that is a child of this Api. |
|
registry/cmd/check/rules/rule103
Api state field is free-form, but we expect single words that describe state.
|
Api state field is free-form, but we expect single words that describe state. |
|
registry/cmd/check/rules/rule104
Api recommended_version must be an ApiVersion that is a child of this Api.
|
Api recommended_version must be an ApiVersion that is a child of this Api. |
|
registry/cmd/check/rules/rule106
ApiDeployment api_spec_revision must be an SpecRevision and sibling under the parent Api.
|
ApiDeployment api_spec_revision must be an SpecRevision and sibling under the parent Api. |
|
registry/cmd/check/rules/rule110
max length of 5k, all characters must use UTF-8 encoding
|
max length of 5k, all characters must use UTF-8 encoding |
|
registry/cmd/check/rules/rule112
Each resource can have multiple labels, up to a maximum of 64.
|
Each resource can have multiple labels, up to a maximum of 64. |
|
registry/cmd/check/rules/rule113
Each resource can have multiple annotations, up to a maximum total size of 256k.
|
Each resource can have multiple annotations, up to a maximum total size of 256k. |
|
General documentation
|
General documentation |
|
pkg
|
|
|
encoding
package encoding provides structs that can be used to serialize YAML files for import with `registry apply`.
|
package encoding provides structs that can be used to serialize YAML files for import with `registry apply`. |
|
server
|
|
|
tools
|
|