Add api-ref for amphora failover

Change-Id: Ie55c54bc48eac966207430d84ec9b2707b058e28

.gitignore

@@ -11,6 +11,7 @@ doc/source/configuration/_static/octavia.policy.yaml.sample
 doc/source/contributor/devref/erd.svg
 doc/source/contributor/devref/flow_diagrams/
 doc/source/contributor/modules
+api-ref/build
 .idea/*
 *.DS_Store
 *.pyc

api-ref/source/v2/amphora.inc

@@ -144,3 +144,44 @@ Response Example
 
 .. literalinclude:: examples/amphora-show-response.json
    :language: javascript
+
+Failover Amphora
+================
+
+.. rest_method:: PUT /v2.0/octavia/amphorae/{amphora_id}/failover
+
+Force an amphora to failover.
+
+If you are not an administrative user, the service returns the HTTP
+``Forbidden (403)`` response code.
+
+This operation does not require a request body.
+
+.. rest_status_code:: success ../http-status.yaml
+
+   - 202
+
+.. rest_status_code:: error ../http-status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 500
+
+Request
+-------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - amphora_id: path-amphora-id
+
+Curl Example
+------------
+
+.. literalinclude:: examples/amphora-failover-curl
+   :language: bash
+
+Response
+--------
+
+There is no body content for the response of a successful PUT request.

api-ref/source/v2/examples/amphora-failover-curl

@@ -0,0 +1 @@
+curl -X PUT -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/octavia/amphorae/6bd55cd3-802e-447e-a518-1e74e23bb106/failover