From 44b77d887a874eb0220d81f1a090c4951fd56683 Mon Sep 17 00:00:00 2001
From: Eric Fried <efried@us.ibm.com>
Date: Mon, 20 Nov 2017 09:38:58 -0600
Subject: [PATCH] placement: Document request headers in api-ref

Briefly document in the Placement API reference:

a) the use of Content-Type: application/json
b) how to use microversion headers, including a link to the main
Microversions reference.

Change-Id: I60d7b9dfe4f1c50fc50eaf07a04848c220ffcf62
---
 placement-api-ref/source/index.rst |  4 ++++
 placement-api-ref/source/root.inc  | 23 ++++++++++++++++++++---
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/placement-api-ref/source/index.rst b/placement-api-ref/source/index.rst
index c76696e86314..a56001169486 100644
--- a/placement-api-ref/source/index.rst
+++ b/placement-api-ref/source/index.rst
@@ -8,6 +8,10 @@ This is a reference for the Openstack Placement API. To learn more about
 Openstack Placement API concepts, please refer to the
 `Placement Introduction <https://docs.openstack.org/nova/latest/user/placement.html>`_.
 
+The Placement API uses JSON for data exchange.  As such, the ``Content-Type``
+header for APIs sending data payloads in the request body (i.e. ``PUT`` and
+``POST``) must be set to ``application/json`` unless otherwise noted.
+
 .. rest_expand_all::
 
 .. include:: root.inc
diff --git a/placement-api-ref/source/root.inc b/placement-api-ref/source/root.inc
index edf9e6347944..23911106dea9 100644
--- a/placement-api-ref/source/root.inc
+++ b/placement-api-ref/source/root.inc
@@ -1,6 +1,23 @@
-========
-Versions
-========
+============
+API Versions
+============
+
+In order to bring new features to users over time, the Placement API
+supports microversioning.  Microversions allow use of certain features on a
+per-request basis via the ``OpenStack-API-Version`` header.  For example, to
+request microversion 1.10, specify the header::
+
+  Openstack-API-Version: placement 1.10
+
+For more details about Microversions, please reference:
+`Microversions
+<https://developer.openstack.org/api-guide/compute/microversions.html>`_
+
+.. note:: The maximum microversion supported by each release varies.
+  Please reference:
+  `REST API Version History
+  <https://docs.openstack.org/nova/latest/user/placement.html#rest-api-version-history>`__
+  for API microversion history details.
 
 List Versions
 =============