AIP-9

Glossary

In the name of brevity, this AIP defines some common terminology here rather than in each AIP individually.

Guidance

The following terminology should be used consistently throughout AIPs.

API

Application Programming Interface. This can be a local interface (such as a client library) or a Network API (defined below).

API Backend

A set of servers and related infrastructure that implements the business logic for an API Service. An individual API backend server is often called an API server.

API Consumer

The entity that consumes an API Service. For Google APIs, it typically is a Google project that owns the client application or the server resource.

API Definition

The definition of an API, usually defined in a Protocol Buffer service. An API Definition can be implemented by any number of API Services.

API Frontend

A set of servers plus related infrastructure that provides common functionality across API Services, such as load balancing and authentication. An individual API frontend server is often called an API proxy.

Note: the API frontend and the API backend may run next to each other or far away from each other. In some cases, they can be compiled into a single application binary and run inside a single process.

API Method

An individual operation within an API. It is typically represented in Protocol Buffers by an rpc definition, and is mapped to a function in the API in most programming languages.

API Producer

The entity that produces an API Service. For Google APIs, it typically is a Google team responsible for the API Service.

API Product

An API Service and its related components, such as Terms of Service, documentation, client libraries, and service support, are collectively presented to customers as a API Product. For example, Google Calendar API.

Note: people sometimes refer to an API Product simply as an API.

API Service

A deployed implementation of one or more APIs, exposed on one or more network addresses, such as the Cloud Pub/Sub API.

API Service Definition

The combination of API Definitions (.proto files) and API Service configurations (.yaml files) used to define an API Service. The schema for Google API Service Definition is google.api.Service.

API Service Endpoint

Refers to a network address that an API Service uses to handle incoming API Requests. One API Service may have multiple API Service Endpoints, such as https://pubsub.googleapis.com and https://content-pubsub.googleapis.com.

API Service Name

Refers to the logical identifier of an API Service. Google APIs use RFC 1035 DNS compatible names as their API Service Names, such as pubsub.googleapis.com.

API Request

A single invocation of an API Method. It is often used as the unit for billing, logging, monitoring, and rate limiting.

API Version

The version of an API or a group of APIs if they are defined together. An API Version is often represented by a string, such as "v1", and presents in API requests and Protocol Buffers package names.

Google API

A Network API exposed by a Google service. Most of these are hosted on the googleapis.com domain. It does not include other types of APIs, such as client libraries and SDKs.

IaC

Short for Infrastructure-as-code, IaC describes a category of clients that consumes a markup language or code that represents resources exposed by an API, and executes the appropriate imperative actions to drive the resource to that desired state.

Examples of complexities that IaC clients abstract away include:

  • Determing the appropriate imperative action (create / update / delete) to achieve desired state.
  • Ordering of these imperative actions.

Terraform is an example of such a client.

Network API

An API that operates across a network of computers. Network APIs communicate using network protocols including HTTP, and are frequently produced by organizations separate from those that consume them.

Changelog

  • 2023-04-01: Adding definition of IaC
  • 2023-03-24: Reformatting content to include anchor links.