Skip to content

Latest commit

 

History

History
157 lines (119 loc) · 7.21 KB

README.md

File metadata and controls

157 lines (119 loc) · 7.21 KB
Raw

Go Actions Status Go Report Card codecov In Solidarity

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.20 (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 -remote flag, tests are run against a remote server according to the configuration used by the registry tool. This runs the entire suite of tests. WARNING: These tests are destructive and will overwrite everything in the remote server.
  • With the -hosted PROJECT_ID flag, 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 the registry tool. 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.