• File Bug
• View source
• Edit this page

AIP-9

Glossary

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

Guidance

The following terminologyshould be used consistently throughout AIPs.

API

Application programming interface. This can be a local interface (such as aclient library) or a Network API (defined below).

API backend

A set of servers and related infrastructure that implements the business logicfor an API service. An individual API backend server is often called an APIserver.

API consumer

The entity that consumes an API service. For Google APIs, it typically is aGoogle 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 APIdefinition can be implemented by any number of API services.

API frontend

A set of servers plus related infrastructure that provides common functionalityacross API services, such as load balancing and authentication. An individualAPI frontend server is often called an API proxy.

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

API interface

The element of an API specification IDL that groups API methods, such as aProtocol Buffersservice definition. It is typically mapped to a similar highlevel grouping mechanism in most programming languages, like aclass orinterface.

API method

An individual operation within an API. It is typically represented in ProtocolBuffers by anrpc definition, and is mapped to a function in the API in mostprogramming languages.

API producer

The entity that produces an API service. For Google APIs, it typically is aGoogle 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 presentedto 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 networkaddresses, such as the Cloud Pub/Sub API.

API service definition

The combination of API definitions (.proto files) and API serviceconfigurations (.yaml files) used to define an API service. The schema forGoogle API service definition isgoogle.api.Service.

API service endpoint

Refers to a network address that an API service uses to handle incoming APIrequests. One API service may have multiple API service endpoints, such ashttps://pubsub.googleapis.com andhttps://content-pubsub.googleapis.com.

API service name

Refers to the logical identifier of an API service. Google APIs use RFC 1035 DNScompatible names as their API service names, such aspubsub.googleapis.com.

API title

Refers to the user-facing product title of an API service, such as "Cloud Pub/SubAPI".

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 APIversion is often represented by a string, such as "v1", and presents in APIrequests and Protocol Buffers package names.

Client

Clients are programs that perform a specific tasks by calling an API or generictools, such as CLIs, that expose the API in a user-accessible fashion or operateon resource data at rest.

Examples of clients include the following:

• Command line interfaces
• Libraries, such as an SDK for a particular programming language
• Scripts that operates on a JSON representation of a resource after reading it from an API
• Tools, such as aDeclarative clients
• Visual UIs, such as a web application

Google API

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

Declarative Clients

Declarative Clients, also known as Infrastructure as Code (IaC), describes acategory of clients that consumes a markup language or code that representsresources exposed by an API, and executes the appropriate imperative actions todrive the resource to that desired state. To determine what changes to make andif a set of updates was successful a declarative client compares server sideresource attributes with client defined values. The comparison feature ensuresaccuracy of a creation or an update but it requires services to treat the clientset fields as read-only and diligently preserve those values.

Examples of complexities that declarative clients abstract away include:

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

Terraform is an example of such a client.

User

A human being which is using an API directly, such as with cURL. This term isdefined to differentiate usage in the AIPs between a humanuser and aprogrammaticclient.

Network API

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

Changelog

• 2025-08-13: Add API inteface entry
• 2024-12-18: Downcase headings and terms as per dev docs style
• 2024-10-23: Add API Title entry
• 2023-07-24: Rename IaC to Declarative Clients
• 2023-04-01: Adding definition of IaC
• 2023-03-24: Reformatting content to include anchor links.