registry

README

Registry API Core Implementation

This repository contains the core implementation of the Registry API.

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.

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 sample Go GAPIC-based client is in examples/gapic-client.

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.

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.