Skip to content

Commit 63aa5ed

Browse files
authored
feat(AIP-9) add section headers (#1051)
Section headers produce anchor links which allows for the ability to link to Glossary terms in other AIPs. Sections have been organized alphabetically for easier discovery. This change is purely organizational. No content was changed as part of this commit.
1 parent 9d2472e commit 63aa5ed

1 file changed

Lines changed: 74 additions & 38 deletions

File tree

aip/general/0009.md

Lines changed: 74 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -16,68 +16,104 @@ than in each AIP individually.
1616

1717
The following terminology **should** be used consistently throughout AIPs.
1818

19-
API : Application Programming Interface. This can be a local interface (such as
20-
a client library) or a Network API (defined below).
21-
22-
Network API : An API that operates across a network of computers. Network APIs
23-
communicate using network protocols including HTTP, and are frequently produced
24-
by organizations separate from those that consume them.
19+
### API
2520

26-
Google API : A Network API exposed by a Google service. Most of these are
27-
hosted on the `googleapis.com` domain. It does not include other types of APIs,
28-
such as client libraries and SDKs.
29-
30-
API Definition : The definition of an API, usually defined in a Protocol Buffer
31-
service. An API Definition can be implemented by any number of API Services.
21+
Application Programming Interface. This can be a local interface (such as
22+
a client library) or a Network API (defined below).
3223

33-
API Version : The version of an API or a group of APIs if they are defined
34-
together. An API Version is often represented by a string, such as "v1", and
35-
presents in API requests and Protocol Buffers package names.
24+
### API Backend
3625

37-
API Method : An individual operation within an API. It is typically represented
38-
in Protocol Buffers by an `rpc` definition, and is mapped to a function in the
39-
API in most programming languages.
26+
A set of servers and related infrastructure that implements the
27+
business logic for an API Service. An individual API backend server is often
28+
called an API server.
4029

41-
API Request : A single invocation of an API Method. It is often used as the
42-
unit for billing, logging, monitoring, and rate limiting.
30+
### API Consumer
4331

44-
API Consumer : The entity that consumes an API Service. For Google APIs, it
32+
The entity that consumes an API Service. For Google APIs, it
4533
typically is a Google project that owns the client application or the server
4634
resource.
4735

48-
API Producer : The entity that produces an API Service. For Google APIs, it
49-
typically is a Google team responsible for the API Service.
36+
### API Definition
5037

51-
API Backend : A set of servers and related infrastructure that implements the
52-
business logic for an API Service. An individual API backend server is often
53-
called an API server.
38+
The definition of an API, usually defined in a Protocol Buffer
39+
service. An API Definition can be implemented by any number of API Services.
5440

55-
API Frontend : A set of servers plus related infrastructure that provides
41+
### API Frontend
42+
43+
A set of servers plus related infrastructure that provides
5644
common functionality across API Services, such as load balancing and
5745
authentication. An individual API frontend server is often called an API proxy.
5846

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

63-
API Service : A deployed implementation of one or more APIs, exposed on one or
64-
more network addresses, such as the Cloud Pub/Sub API.
51+
### API Method
6552

66-
API Service Name : Refers to the logical identifier of an API Service. Google
67-
APIs use RFC 1035 DNS compatible names as their API Service Names, such as
68-
`pubsub.googleapis.com`.
53+
An individual operation within an API. It is typically represented
54+
in Protocol Buffers by an `rpc` definition, and is mapped to a function in the
55+
API in most programming languages.
6956

70-
API Service Endpoint : Refers to a network address that an API Service uses to
71-
handle incoming API Requests. One API Service may have multiple API Service
72-
Endpoints, such as `https://pubsub.googleapis.com` and
73-
`https://content-pubsub.googleapis.com`.
57+
### API Producer
58+
59+
The entity that produces an API Service. For Google APIs, it
60+
typically is a Google team responsible for the API Service.
7461

75-
API Product : An API Service and its related components, such as Terms of
62+
### API Product
63+
64+
An API Service and its related components, such as Terms of
7665
Service, documentation, client libraries, and service support, are collectively
7766
presented to customers as a API Product. For example, Google Calendar API.
7867

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

81-
API Service Definition : The combination of API Definitions (`.proto` files)
70+
### API Service
71+
72+
A deployed implementation of one or more APIs, exposed on one or
73+
more network addresses, such as the Cloud Pub/Sub API.
74+
75+
### API Service Definition
76+
77+
The combination of API Definitions (`.proto` files)
8278
and API Service configurations (`.yaml` files) used to define an API Service.
8379
The schema for Google API Service Definition is `google.api.Service`.
80+
81+
### API Service Endpoint
82+
83+
Refers to a network address that an API Service uses to
84+
handle incoming API Requests. One API Service may have multiple API Service
85+
Endpoints, such as `https://pubsub.googleapis.com` and
86+
`https://content-pubsub.googleapis.com`.
87+
88+
### API Service Name
89+
90+
Refers to the logical identifier of an API Service. Google
91+
APIs use RFC 1035 DNS compatible names as their API Service Names, such as
92+
`pubsub.googleapis.com`.
93+
94+
### API Request
95+
96+
A single invocation of an API Method. It is often used as the
97+
unit for billing, logging, monitoring, and rate limiting.
98+
99+
### API Version
100+
101+
The version of an API or a group of APIs if they are defined
102+
together. An API Version is often represented by a string, such as "v1", and
103+
presents in API requests and Protocol Buffers package names.
104+
105+
### Google API
106+
107+
A Network API exposed by a Google service. Most of these are
108+
hosted on the `googleapis.com` domain. It does not include other types of APIs,
109+
such as client libraries and SDKs.
110+
111+
### Network API
112+
113+
An API that operates across a network of computers. Network APIs
114+
communicate using network protocols including HTTP, and are frequently produced
115+
by organizations separate from those that consume them.
116+
117+
## Changelog
118+
119+
- **2023-03-24**: Reformatting content to include anchor links.

0 commit comments

Comments
 (0)