docs: first draft annotation api

Author: bmorelli25

docs/apm/api.asciidoc

@@ -9,14 +9,19 @@
 Some APM app features are provided via a REST API:
 
 * <<agent-config-api>>
+* <<annotation-api>>
 
 TIP: Kibana provides additional <<api,REST APIs>>,
 and general information on <<using-api,how to use APIs>>.
 
+// Basic auth or API can be used
+// Need to talk about permissions req'd
+
 ////
 *******************************************************
 ////
 
+[role="xpack"]
 [[agent-config-api]]
 === Agent Configuration API
 
@@ -274,6 +279,116 @@ POST /api/apm/settings/agent-configuration/search
 }
 --------------------------------------------------
 
+////
+*******************************************************
+*******************************************************
+////
+
+[role="xpack"]
+[[apm-annotation-api]]
+=== Annotation API
+
+The Annotation API allows you to annotate visualizations in the APM app with significant events, like deployments,
+allowing you to easily see how these events are impacting the performance of your existing applications.
+
+The following APIs are available:
+
+* <<apm-annotation-create>> to create an annotation for APM.
+// * <<obs-annotation-create>> POST /api/observability/annotation
+// * <<obs-annotation-get>> GET /api/observability/annotation/:id
+// * <<obs-annotation-delete>> DELETE /api/observability/annotation/:id
+
+By default, annotations are stored in a newly created `observability-annotations` index.
+The name of this index is configurable with `CONFIG_NAME_AND_LINK_HERE`.
+
 ////
 *******************************************************
 ////
+
+[[apm-annotation-config]]
+==== Create or update annotation
+
+[[apm-annotation-config-req]]
+===== Request
+
+`POST /api/apm/services/:serviceName/annotation`
+
+[role="child_attributes"]
+[[apm-annotation-config-req-body]]
+===== Request body
+
+`service`::
+(required, object) Service identifying the configuration to create or update.
++
+.Properties of `service`
+[%collapsible%open]
+======
+`version` :::
+  (required, string) Name of service.
+
+`environment` :::
+  (optional, string) Environment of service.
+======
+
+`@timestamp`::
+(required, string) The date and time of the annotation. Must be in https://www.w3.org/TR/NOTE-datetime[ISO 8601] format.
+
+`message`::
+(optional, string) The message displayed in the annotation. Defaults to `service.version`.
+
+`tags`::
+(optional, array) Tags that are useful for what? Defaults to `[apm]`.
+
+[[apm-annotation-config-example]]
+===== Example
+
+The following example creates an annotation for a service named `opbeans-java`.
+
+[source,console]
+--------------------------------------------------
+POST /api/apm/services/opbeans-java/annotation
+{
+	"@timestamp": "2020-05-08T10:31:30.452Z",
+	"service": {
+		"version": "1.2"
+	},
+	"message": "Deployment 1.2",
+	"tags": [
+		"elastic.co", "customer"
+	]
+}
+--------------------------------------------------
+
+[[apm-annotation-config-body]]
+===== Response body
+
+[source,js]
+--------------------------------------------------
+{
+  "_index": "observability-annotations",
+  "_id": "Lc9I93EBh6DbmkeV7nFX",
+  "_version": 1,
+  "_seq_no": 12,
+  "_primary_term": 1,
+  "found": true,
+  "_source": {
+    "message": "Deployment 1.2",
+    "@timestamp": "2020-05-08T10:31:30.452Z",
+    "service": {
+      "version": "1.2",
+      "name": "opbeans-java"
+    },
+    "tags": [
+      "apm",
+      "elastic.co",
+      "customer"
+    ],
+    "annotation": {
+      "type": "deployment"
+    },
+    "event": {
+      "created": "2020-05-09T02:34:43.937Z"
+    }
+  }
+}
+--------------------------------------------------

docs/apm/deployment-annotations.asciidoc

@@ -3,15 +3,19 @@
 === Track deployments with annotations
 
 ++++
-<titleabbrev>Track deployments</titleabbrev>
+<titleabbrev>Track deployments with annotations</titleabbrev>
 ++++
 
 For enhanced visibility into your deployments, we offer deployment annotations on all transaction charts.
 This feature automatically tags new deployments, so you can easily see if your deploy has increased response times
 for an end-user, or if the memory/CPU footprint of your application has changed.
 Being able to identify bad deployments quickly enables you to rollback and fix issues without causing costly outages.
 
-Deployment annotations are automatically enabled, and appear when the `service.version` of your app changes.
+Deployment annotations are enabled by default, and can be created with the <<apm-annotation-api,annotation API>>.
+If there are no created annotations for the selected time period,
+the APM app will automatically annotate your data if the `service.version` of your application changes.
+
+NOTE: If custom annotations have been created for the selected time period, any derived annotations, i.e., those created automatically when `service.version` changes, will not be shown.
 
 [role="screenshot"]
 image::apm/images/apm-transaction-annotation.png[Example view of transactions annotation in the APM app in Kibana]

docs/apm/images/apm-transaction-annotation.png

@@ -74,6 +74,9 @@ Changing these settings may disable features of the APM App.
 | `apm_oss.sourcemapIndices`
   | Matcher for all {apm-server-ref}/sourcemap-indices.html[source map indices]. Defaults to `apm-*`.
 
+| New setting
+  | New setting description
+
 |===
 
 // end::general-apm-settings[]