| [ Web Proxy ] |
| Viewing: https://cloud.google.com/apis/design/glossary#api_service_endpoint | [Back] [Original] |
[github.png]
View on GitHub
| Glossary | |
|---|---|
| Number | 9 |
| Permalink | google.aip.dev/9 |
| State | Approved |
| Created | 2019-08-01 |
| Updated | 2019-08-01 |
In the name of brevity, this AIP defines some common terminology here rather than in each AIP individually.
The following terminology should be used consistently throughout AIPs.
Application programming interface. This can be a local interface (such as a client library) or a Network API (defined below).
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.
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.
The definition of an API, usually defined in a Protocol Buffer service. An API definition can be implemented by any number of API services.
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.
The element of an API specification IDL that groups API methods, such as a
Protocol Buffers service definition. It is typically mapped to a similar high
level grouping mechanism in most programming languages, like a class or
interface.
A distinct iteration of an API interface represented by an API version identifier. A constituent part of an API service version.
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.
The entity that produces an API service. For Google APIs, it typically is a Google team responsible for the API service.
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.
A deployed implementation of one or more APIs, exposed on one or more network addresses, such as the Cloud Pub/Sub API.
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.
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.
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.
A distinct set of API interfaces and their contemporaneous API interface versions. It is scoped to an API variant. The API service version value is typically equal to the latest API interface version in that set. The content of API artifacts, such as reference documentation, client library packages, and other API-based tooling, are often organized around one or more service versions.
Refers to the user-facing product title of an API service, such as "Cloud Pub/Sub API".
A single invocation of an API method. It is often used as the unit for billing, logging, monitoring, and rate limiting.
The top-level iteration of an API, such as "v1beta" or "v2", that appears in API artifacts such as specifications, client packages, and folder-filesystem structure. API variants are producer-defined shorthands that demarcate side-by-side namespaces for API interface versions.
API version is used colloquially in reference to any of the following:
Prefer to use the more specific term wherever possible.
The name of a versioned iteration of an API interface, such as 2024-10-31.
It is the "key" to clients and services communicating via the same API. See
AIP-184 for more detail on version identifiers.
Clients are programs that perform a specific tasks by calling an API or generic tools, such as CLIs, that expose the API in a user-accessible fashion or operate on resource data at rest.
Examples of clients include the following:
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.
Declarative Clients, also known as 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. To determine what changes to make and if a set of updates was successful a declarative client compares server side resource attributes with client defined values. The comparison feature ensures accuracy of a creation or an update but it requires services to treat the client set fields as read-only and diligently preserve those values.
Examples of complexities that declarative clients abstract away include:
Terraform is an example of such a client.
A human being which is using an API directly, such as with cURL. This term is defined to differentiate usage in the AIPs between a human user and a programmatic client.
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.
| Web Proxy Viewer | New URL | Original Page |
![[github.png]](https://cloud.google.com/assets/images/github.png){kind=link}