feat(AIP-9): adding client term (#1113)

The term "client" is not well-defined in the AIPs. Doing
so will help clarify the categories, especially that both
programmatic and direct user clients exist.

Author: toumorokoshi

aip/general/0009.md

@@ -18,95 +18,107 @@ 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).
+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.
+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.
+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.
+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.
+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
+**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.
+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.
+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.
+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.
+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`.
+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`.
+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`.
+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.
+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.
+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.
+
+### Client
+
+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:
+
+- 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 an [IaC][] client
+- Visual UIs, such as a web application
 
 ### 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.
+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
 
@@ -117,17 +129,25 @@ desired state.
 
 Examples of complexities that IaC clients abstract away include:
 
-- Determing the appropriate imperative action (create / update / delete) to achieve desired state.
+- 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.
 
+### User
+
+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*.
+
 ### 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.
+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.
 
+[IaC]: #iac
 [Terraform]: https://www.terraform.io/
 
 ## Changelog