Add api-ref for allocation update

Change-Id: I3a8cfa3d959c6906968bca7006583f45446758e5
Story: 2005126
Task: 29796

api-ref/source/baremetal-api-v1-allocation.inc

@@ -183,6 +183,62 @@ Response Example
 .. literalinclude:: samples/allocation-show-response.json
    :language: javascript
 
+Update Allocation
+=================
+
+.. rest_method::  PATCH /v1/allocations/{allocation_id}
+
+Updates an allocation. Allows updating only name and extra fields.
+
+.. versionadded:: 1.57
+    Allocation update API was introduced.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 403, 404, 409, 503
+
+Request
+-------
+
+The BODY of the PATCH request must be a JSON PATCH document, adhering to
+`RFC 6902 <https://tools.ietf.org/html/rfc6902>`_.
+
+.. rest_parameters:: parameters.yaml
+
+   - allocation_id: allocation_ident
+   - name: req_allocation_name
+   - extra: req_extra
+
+Request Example
+---------------
+
+.. literalinclude:: samples/allocation-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - uuid: uuid
+   - candidate_nodes: candidate_nodes
+   - last_error: allocation_last_error
+   - name: allocation_name
+   - node_uuid: allocation_node
+   - resource_class: allocation_resource_class
+   - state: allocation_state
+   - traits: allocation_traits
+   - extra: extra
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+Response Example
+----------------
+
+.. literalinclude:: samples/allocation-update-response.json
+   :language: javascript
+
 Delete Allocation
 =================
 

api-ref/source/samples/allocation-update-request.json

@@ -0,0 +1,7 @@
+[
+    {
+        "op": "add",
+        "path": "/extra/foo",
+        "value": "bar"
+    }
+]

api-ref/source/samples/allocation-update-response.json

@@ -0,0 +1,26 @@
+{
+  "node_uuid": null,
+  "uuid": "241db410-7b04-4b1c-87ae-4e336435db08",
+  "links": [
+    {
+      "href": "http://10.66.169.122/v1/allocations/241db410-7b04-4b1c-87ae-4e336435db08",
+      "rel": "self"
+    },
+    {
+      "href": "http://10.66.169.122/allocations/241db410-7b04-4b1c-87ae-4e336435db08",
+      "rel": "bookmark"
+    }
+  ],
+  "extra":
+    {
+      "foo": "bar"
+    },
+  "last_error": null,
+  "created_at": "2019-06-04T07:46:25+00:00",
+  "resource_class": "CUSTOM_GOLD",
+  "updated_at": "2019-06-06T03:28:19.496960+00:00",
+  "traits": [],
+  "state": "error",
+  "candidate_nodes": [],
+  "name": "test_allocation"
+}