[docs] Rename intake API (#3283) (#3293)

docs/agent-configuration.asciidoc

@@ -16,7 +16,7 @@ Send an `HTTP GET` request to the agent configuration endpoint.
 http(s)://{hostname}:{port}/config/v1/agents?service.name=SERVICE_NAME
 ------------------------------------------------------------
 
-If a <<secret-token,`secret_token`>> has been configured, it should also apply to this endpoint.
+If an <<api-key>> or <<secret-token>> has been configured, it will also apply to this endpoint.
 
 [[agent-config-api-response]]
 [float]

docs/events-api.asciidoc

@@ -1,16 +1,26 @@
 [[events-api]]
-== Events API
+== Events Intake API
 
-Agents capture different types of information, known as events.
-These events are sent to a single endpoint which then sorts and processes the events.
+NOTE: Most users do not need to interact directly with the events intake API.
+
+The events intake API is what we call the internal protocol that APM agents use to talk to the APM Server.
+Agents communicate with the Server by sending events -- captured pieces of information -- in an HTTP request.
 Events can be:
 
 * Transactions
 * Spans
 * Errors
 * Metrics
 
-You can learn more about events in the {apm-overview-ref-v}/apm-data-model.html[APM Data Model]. 
+Each event is sent as its own line in the HTTP request body.
+This is known as http://ndjson.org[newline delimited JSON (NDJSON)].
+
+With NDJSON, agents can open an HTTP POST request and use chunked encoding to stream events to the APM Server
+as soon as they are recorded in the agent.
+This makes it simple for agents to serialize each event to a stream of newline delimited JSON.
+The APM Server also treats the HTTP body as a compressed stream and thus reads and handles each event independently.
+
+See the {apm-overview-ref-v}/apm-data-model.html[APM Data Model] to learn more about the different types of events.
 
 [[events-api-endpoint]]
 [float]
@@ -40,7 +50,7 @@ Keep in mind that events can succeed and fail independently of each other. Only
 
 [[events-api-errors]]
 [float]
-==== Errors
+=== Errors
 
 There are two types of errors that the APM Server may return to an agent:
 
@@ -90,20 +100,20 @@ An example error response might look something like this:
 <3> An immediately returning non-event related error
 <4> The number of accepted events
 
-If you're developing an agent, these errors can be useful for debugging your agent while building it. 
+If you're developing an agent, these errors can be useful for debugging. 
 
 [[events-api-schema-definition]]
 [float]
 === Event API Schemas
 
 The APM Server uses a collection of JSON Schemas for validating requests to the intake API:
 
-* <<metadata-api, Metadata>>
-* <<transaction-api, Transactions>>
-* <<span-api, Spans>>
-* <<error-api, Errors>>
-* <<metricset-api, Metrics>>
-* <<example-intake-events, Example Request Body>>
+* <<metadata-api>>
+* <<transaction-api>>
+* <<span-api>>
+* <<error-api>>
+* <<metricset-api>>
+* <<example-intake-events>>
 
 include::./metadata-api.asciidoc[]
 include::./transaction-api.asciidoc[]

docs/intake-api.asciidoc

@@ -1,36 +1,16 @@
 [[intake-api]]
-= Intake API
+= API
+
 [partintro]
 --
-NOTE: Most users will not need to interact directly with the intake API unless they are implementing an agent.
-
-The Intake API is what we call the internal protocol that APM agents use to talk to the APM Server.
-
-APM agents communicate with the APM server by sending events in an HTTP request.
-Each event is sent as its own line in the HTTP request body.
-This is known as http://ndjson.org[newline delimited JSON (NDJSON)].
-The request body looks roughly like this:
-
-[source,bash]
-------------------------------------------------------------
-{"metadata": {"service": {"name": "ecommerce-front"}}}
-{"span": {"name": "SELECT FROM products", "duration": 323, "transaction_id": "A"}}
-{"span": {"name": "SELECT FROM users", "duration": 202, "transaction_id": "A"}}
-{"transaction": {"name": "GET /index", "id": "A"}}
-------------------------------------------------------------
-
-With NDJSON, agents can open an HTTP POST request and use chunked encoding to stream events to the APM Server as soon as they are recorded in the agent.
-This makes it simple for agents to serialize each event to a stream of newline delimited JSON.
-
-The APM Server also treats the HTTP body as a compressed stream and thus reads and handles each event independently.
-
-The APM Server exposes endpoints for
-
-* <<events-api,Events>>
-* <<sourcemap-api,Source Map Upload>>
-* <<server-info,Server Information>>
+The APM Server exposes endpoints for:
 
+* <<events-api,Events intake>>
+* <<sourcemap-api,Sourcemap upload>>
+* <<agent-configuration-api,Agent configuration>>
+* <<server-info,Server information>>
 --
+
 include::./events-api.asciidoc[]
 include::./sourcemap-api.asciidoc[]
 include::./agent-configuration.asciidoc[]

docs/server-info.asciidoc

@@ -16,7 +16,7 @@ http(s)://{hostname}:{port}/
 
 This endpoint always returns an HTTP 200.
 
-If a <<secret-token, secret token>> is set, only requests including <<config-secret-token, authentication>> will receive server details.
+If an <<api-key>> or <<secret-token>> is set, only requests including <<secure-communication-agents,authentication>> will receive server details.
 
 Set the `Accept` header set to `text/plain` to move the server information to the root level of the response, removing `ok`.
 

docs/sourcemap-api.asciidoc

@@ -27,7 +27,7 @@ The request must include some fields needed to identify `source map` correctly l
 The source map must follow the
 https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k[Source map revision 3 proposal] spec and be attached as a `file upload`.
 
-You can configure a <<secret-token, secret token>> to upload sourcemaps.
+You can configure an <<api-key>> or <<secret-token>> to upload sourcemaps.
 
 [[sourcemap-api-examples]]
 [float]