From 6848fe0edf0480eda09efa300f075ac4f560b3ee Mon Sep 17 00:00:00 2001
From: Marcus Efraimsson <marcus.efraimsson@gmail.com>
Date: Wed, 6 Feb 2019 14:26:43 +0100
Subject: [PATCH] docs: update annotaions http api

---
 docs/sources/http_api/annotations.md | 50 +++++++++++++++++++++-------
 1 file changed, 38 insertions(+), 12 deletions(-)

diff --git a/docs/sources/http_api/annotations.md b/docs/sources/http_api/annotations.md
index ca589581f96..e1d2876f48a 100644
--- a/docs/sources/http_api/annotations.md
+++ b/docs/sources/http_api/annotations.md
@@ -97,7 +97,7 @@ Creates an annotation in the Grafana database. The `dashboardId` and `panelId` f
 
 **Example Request**:
 
-```json
+```http
 POST /api/annotations HTTP/1.1
 Accept: application/json
 Content-Type: application/json
@@ -115,7 +115,7 @@ Content-Type: application/json
 
 **Example Response**:
 
-```json
+```http
 HTTP/1.1 200
 Content-Type: application/json
 
@@ -135,7 +135,7 @@ format (string with multiple tags being separated by a space).
 
 **Example Request**:
 
-```json
+```http
 POST /api/annotations/graphite HTTP/1.1
 Accept: application/json
 Content-Type: application/json
@@ -150,7 +150,7 @@ Content-Type: application/json
 
 **Example Response**:
 
-```json
+```http
 HTTP/1.1 200
 Content-Type: application/json
 
@@ -160,15 +160,15 @@ Content-Type: application/json
 }
 ```
 
-## Replace Annotation
+## Update Annotation
 
 `PUT /api/annotations/:id`
 
-Replaces the annotation that matches the specified id.
+Updates all properties of an annotation that matches the specified id. To only update certain property, consider using the [Patch Annotation](#patch-annotation) operation.
 
 **Example Request**:
 
-```json
+```http
 PUT /api/annotations/1141 HTTP/1.1
 Accept: application/json
 Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
@@ -183,17 +183,28 @@ Content-Type: application/json
 }
 ```
 
-## Update Annotation
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+{
+    "message":"Annotation updated"
+}
+```
+
+## Patch Annotation
 
 `PATCH /api/annotations/:id`
 
 Updates one or more properties of an annotation that matches the specified id.
 
-The `PATCH` operation currently supports updating of the `text`, `tags`, `time` and `timeEnd` properties. It does not handle updating of the `isRegion` and `regionId` properties. To make an annotation regional or vice versa, consider using the `PUT` operation.
+This operation currently supports updating of the `text`, `tags`, `time` and `timeEnd` properties. It does not handle updating of the `isRegion` and `regionId` properties. To make an annotation regional or vice versa, consider using the [Update Annotation](#update-annotation) operation.
 
 **Example Request**:
 
-```json
+```http
 PATCH /api/annotations/1145 HTTP/1.1
 Accept: application/json
 Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
@@ -205,6 +216,17 @@ Content-Type: application/json
 }
 ```
 
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+{
+    "message":"Annotation patched"
+}
+```
+
 ## Delete Annotation By Id
 
 `DELETE /api/annotations/:id`
@@ -226,7 +248,9 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 HTTP/1.1 200
 Content-Type: application/json
 
-{"message":"Annotation deleted"}
+{
+    "message":"Annotation deleted"
+}
 ```
 
 ## Delete Annotation By RegionId
@@ -250,5 +274,7 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 HTTP/1.1 200
 Content-Type: application/json
 
-{"message":"Annotation region deleted"}
+{
+    "message":"Annotation region deleted"
+}
 ```