Repository files navigation

This repository contains the core implementation of the Registry API. Please seethewiki for more information.

The Registry API allows teams to upload and share machine-readable descriptionsof APIs that are in use and in development. These descriptions include APIspecifications in standard formats likeOpenAPI,theGoogle API Discovery Service Format,and theProtocol Buffers Language.These API specifications can be used by tools like linters, browsers,documentation generators, test runners, proxies, and API client and servergenerators. The Registry API itself can be seen as a machine-readable enterpriseAPI catalog designed to back online directories, portals, and workflow managers.

The Registry API is formally described by the Protocol Buffer source files ingoogle/cloud/apigeeregistry/v1. It closelyfollows the Google API Design Guidelines ataip.dev andpresents a developer experience consistent with production Google APIs. Pleasetell us about your experience if you use it.

The Registry Tool (registry) is a command-line tool that simplifies setup andoperation of a registry. Seecmd/registry andthe Registry wiki for moreinformation. Theregistry tool can be built from sources here or installedwith this script on Linux or Darwin:

curl -L https://raw.githubusercontent.com/apigee/registry/main/downloadLatest.sh | sh -

This implementation is agRPC service written in Go. It canbe run locally or deployed in a container using services includingGoogle Cloud Run. It stores data using aconfigurable relational interface layer that currently supportsPostgreSQL andSQLite.

The Registry API service is annotated to supportgRPC HTTP/JSON transcoding, which allows it to beautomatically published as a JSON REST API using a proxy. Proxies also enablegRPC web, which allows gRPC calls to bedirectly made from browser-based applications. A configuration for theEnvoy proxy is included(deployments/envoy/envoy.yaml).

The Registry API protos also include configuration to supportgenerated API clients (GAPICS),which allow idiomatic API usage from a variety of languages. A Go GAPIC libraryis generated as part of the build process usinggapic-generator-go.

A command-line interface is incmd/registry and provides amixture of hand-written high-level features and automatically generatedsubcommands that call individual RPC methods of the Registry API.

The entry point for the Registry API server itself iscmd/registry-server. For more on running the server, seecmd/registry-server/README.md.

The following tools are needed to build this software:

• Go 1.20 (recommended) or later.
• protoc, the Protocol Buffer Compiler (seetools/PROTOC-VERSION.sh for the currently-usedversion).
• make, git, and other elements of common unix build environments.

This repository contains aMakefile that downloads all otherdependencies and builds this software (make all). With dependenciesdownloaded, subsequent builds can be made withgo install ./... ormake lite.

The easiest way to try the Registry API is to runregistry-server locally. Bydefault, the server is configured to use a SQLite database.

registry-server

Next, in a separate terminal, configure your environment to point to this serverwith the following:

. auth/LOCAL.sh

Now you can check your server and configuration with theregistry tool:

registry rpc admin get-status

Next run a suite of tests withmake test and see a corresponding walkthroughof API features intests/demo/walkthrough.sh. Formore demonstrations, see thedemos directory.

This repository includes tests that verifyregistry-server. These server testsfocus on correctness at the API level and compliance with the API designguidelines described ataip.dev. Server tests are included inruns ofmake test andgo test ./..., and the server tests can be run bythemselves withgo test ./server/registry. By default, server tests verify thelocal code in./server/registry, but to allowAPI conformance testing, thetests can be run to verify remote servers using the following options:

• With the-remote flag, tests are run against a remote server according tothe configuration used by theregistry tool. This runs the entire suite oftests.WARNING: These tests are destructive and will overwrite everythingin the remote server.
• With the-hosted PROJECT_ID flag, tests are run against a remote server in ahosted environment within a single project that is expected to already exist.The server is identified and authenticated with the configuration used by theregistry tool. Only the methods of the Registry service are tested (Adminservice methods are excluded).WARNING: These tests are destructive andwill overwrite everything in the specified project.

A small set ofperformance benchmarks is intests/benchmark. These tests run against remote serversspecified by theregistry tool configuration and test a single project that isexpected to already exist.WARNING: These tests are destructive and willoverwrite everything in the specified project. Benchmarks can be run with thefollowing 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'sCI tests.

This software is licensed under the Apache License, Version 2.0. SeeLICENSE for the full license text.

This is not an official Google product. Issues filed on GitHub are not subjectto service level agreements (SLAs) and responses should be assumed to be on anad-hoc volunteer basis.

Contributions are welcome! Please seeCONTRIBUTING for noteson how to contribute to this project.