From 8d3dd76d9f54ef349324bc816e7a2b84d714c2d9 Mon Sep 17 00:00:00 2001
From: Chris Church <chris@ninemoreminutes.com>
Date: Sat, 28 Sep 2013 16:12:27 -0400
Subject: [PATCH] AC-506. API docs for project/inventory updates.

---
 awx/main/templates/main/_new_in_awx.md         |  1 +
 .../templates/main/inventory_source_cancel.md  | 13 +++++++++++++
 .../main/inventory_source_update_view.md       | 18 ++++++++++++++++++
 .../templates/main/project_update_cancel.md    | 13 +++++++++++++
 awx/main/templates/main/project_update_view.md | 18 ++++++++++++++++++
 .../templates/main/retrieve_update_api_view.md | 16 ++++++++++++++++
 6 files changed, 79 insertions(+)
 create mode 100644 awx/main/templates/main/inventory_source_cancel.md
 create mode 100644 awx/main/templates/main/inventory_source_update_view.md
 create mode 100644 awx/main/templates/main/project_update_cancel.md
 create mode 100644 awx/main/templates/main/project_update_view.md
 create mode 100644 awx/main/templates/main/retrieve_update_api_view.md

diff --git a/awx/main/templates/main/_new_in_awx.md b/awx/main/templates/main/_new_in_awx.md
index 766b41a28d..757ee26e86 100644
--- a/awx/main/templates/main/_new_in_awx.md
+++ b/awx/main/templates/main/_new_in_awx.md
@@ -1 +1,2 @@
 {% if new_in_13 %}> _New in AWX 1.3_{% endif %}
+{% if new_in_14 %}> _New in AWX 1.4_{% endif %}
diff --git a/awx/main/templates/main/inventory_source_cancel.md b/awx/main/templates/main/inventory_source_cancel.md
new file mode 100644
index 0000000000..b5a212bbf6
--- /dev/null
+++ b/awx/main/templates/main/inventory_source_cancel.md
@@ -0,0 +1,13 @@
+# Cancel Inventory Update
+
+Make a GET request to this resource to determine if the inventory update can be
+cancelled.  The response will include the following field:
+
+* `can_cancel`: Indicates whether this update can be canceled (boolean,
+  read-only)
+
+Make a POST request to this resource to cancel a pending or running inventory
+update.  The response status code will be 202 if successful, or 405 if the
+update cannot be canceled.
+
+{% include "main/_new_in_awx.md" %}
diff --git a/awx/main/templates/main/inventory_source_update_view.md b/awx/main/templates/main/inventory_source_update_view.md
new file mode 100644
index 0000000000..b0eb5227f1
--- /dev/null
+++ b/awx/main/templates/main/inventory_source_update_view.md
@@ -0,0 +1,18 @@
+# Update Inventory Source
+
+Make a GET request to this resource to determine if the group can be updated
+from its inventory source and whether any passwords are required for the
+update.  The response will include the following fields:
+
+* `can_start`: Flag indicating if this job can be started (boolean, read-only)
+* `passwords_needed_to_update`: Password names required to update from the
+  inventory source (array, read-only)
+
+Make a POST request to this resource to update the inventory source.  If any
+passwords are required, they must be passed via POST data.
+
+If successful, the response status code will be 202.  If any required passwords
+are not provided, a 400 status code will be returned.  If the inventory source
+is not defined or cannot be updated, a 405 status code will be returned.
+
+{% include "main/_new_in_awx.md" %}
diff --git a/awx/main/templates/main/project_update_cancel.md b/awx/main/templates/main/project_update_cancel.md
new file mode 100644
index 0000000000..3841996e0a
--- /dev/null
+++ b/awx/main/templates/main/project_update_cancel.md
@@ -0,0 +1,13 @@
+# Cancel Project Update
+
+Make a GET request to this resource to determine if the project update can be
+cancelled.  The response will include the following field:
+
+* `can_cancel`: Indicates whether this update can be canceled (boolean,
+  read-only)
+
+Make a POST request to this resource to cancel a pending or running project
+update.  The response status code will be 202 if successful, or 405 if the
+update cannot be canceled.
+
+{% include "main/_new_in_awx.md" %}
diff --git a/awx/main/templates/main/project_update_view.md b/awx/main/templates/main/project_update_view.md
new file mode 100644
index 0000000000..8d051dd2d4
--- /dev/null
+++ b/awx/main/templates/main/project_update_view.md
@@ -0,0 +1,18 @@
+# Update Project
+
+Make a GET request to this resource to determine if the project can be updated
+from its SCM source and whether any passwords are required for the update.  The
+response will include the following fields:
+
+* `can_start`: Flag indicating if this job can be started (boolean, read-only)
+* `passwords_needed_to_update`: Password names required to update the project
+  (array, read-only)
+
+Make a POST request to this resource to update the project.  If any passwords
+are required, they must be passed via POST data.
+
+If successful, the response status code will be 202.  If any required passwords
+are not provided, a 400 status code will be returned.  If the project cannot be
+updated, a 405 status code will be returned.
+
+{% include "main/_new_in_awx.md" %}
diff --git a/awx/main/templates/main/retrieve_update_api_view.md b/awx/main/templates/main/retrieve_update_api_view.md
new file mode 100644
index 0000000000..27e2ca5990
--- /dev/null
+++ b/awx/main/templates/main/retrieve_update_api_view.md
@@ -0,0 +1,16 @@
+{% include "main/retrieve_api_view.md" %}
+
+# Update {{ model_verbose_name|title }}:
+
+Make a PUT or PATCH request to this resource to update this
+{{ model_verbose_name }}.  The following fields may be modified:
+
+{% with write_only=1 %}
+{% include "main/_result_fields_common.md" %}
+{% endwith %}
+
+For a PUT request, include **all** fields in the request.
+
+For a PATCH request, include only the fields that are being modified.
+
+{% include "main/_new_in_awx.md" %}