-
Notifications
You must be signed in to change notification settings - Fork 33
Design Foundations of the Registry
The Registry API was built using practices that allow it to be run standalone and/or offered as a Google Cloud API.
The Protocol Buffers language is a programming-language-neutral way of describing APIs.
Nearly all Google APIs are described with the Protocol Buffers language, which allows APIs to be implemented and used with many different programming languages. With many APIs described in one common language, tooling exists to support API development and operation in many ways that include documentation generation, implementation, and service management.
Using the Protocol Buffers language, API designers write .proto files that describe request and response messages and operations of the API. Operations are defined as remote procedure calls, and by following the resource-oriented design patterns described in AIP-121, developers can create REST-style APIs that use HTTP and JSON using HTTP and gRPC Transcoding (AIP-127).
gRPC is a high performance API framework built on HTTP/2 with many advanced API management features. Protocol Buffer API descriptions can be compiled to create a stub (mocked) API server and automatically-generated clients including command-line interfaces that can be used to test APIs during development. As mentioned above, gRPC Transcoding allows providers to offer HTTP/JSON interfaces alongside pure-gRPC interfaces.
API Improvement Proposals (AIPs) are Google-wide conventions for APIs that govern their design and implementation. By standardizing many features of API architecture (e.g. pagination, AIPs allow teams to build lots of tools that “just work” across AIP-compliant APIs.
The Registry API closely follows the AIPs, allowing it to be implemented as a Google Cloud API. This also allows developers and users to take advantage of many Google API tools including the open source api-linter and code generators published at github.com/googleapis.
For in-depth discussion of the design considerations behind the AIPs, see API Design Patterns by J.J. Geewax.