Moved API code into separate Django app.

awx/api/templates/api/_list_common.md

@@ -0,0 +1,120 @@
+The resulting data structure contains:
+
+    {
+        "count": 99, 
+        "next": null, 
+        "previous": null, 
+        "results": [
+            ...
+        ]
+    }
+
+The `count` field indicates the total number of {{ model_verbose_name_plural }}
+found for the given query.  The `next` and `previous` fields provides links to
+additional results if there are more than will fit on a single page.  The
+`results` list contains zero or more {{ model_verbose_name }} records.  
+
+## Results
+
+Each {{ model_verbose_name }} data structure includes the following fields:
+
+{% include "api/_result_fields_common.md" %}
+
+## Sorting
+
+To specify that {{ model_verbose_name_plural }} are returned in a particular
+order, use the `order_by` query string parameter on the GET request.
+
+    ?order_by={{ order_field }}
+
+Prefix the field name with a dash `-` to sort in reverse:
+
+    ?order_by=-{{ order_field }}
+
+Multiple sorting fields may be specified by separating the field names with a
+comma `,`:
+
+    ?order_by={{ order_field }},some_other_field
+
+## Pagination
+
+Use the `page_size` query string parameter to change the number of results
+returned for each request.  Use the `page` query string parameter to retrieve
+a particular page of results.
+
+    ?page_size=100&page=2
+
+The `previous` and `next` links returned with the results will set these query
+string parameters automatically.
+
+## Searching
+
+Use the `search` query string parameter to perform a case-insensitive search
+within all designated text fields of a model.
+
+    ?search=findme
+
+_New in AWX 1.4_
+
+## Filtering
+
+Any additional query string parameters may be used to filter the list of
+results returned to those matching a given value.  Only fields and relations
+that exist in the database may be used for filtering.  Any special characters
+in the specified value should be url-encoded. For example:
+
+    ?field=value%20xyz
+
+Fields may also span relations, only for fields and relationships defined in
+the database: 
+
+    ?other__field=value
+
+To exclude results matching certain criteria, prefix the field parameter with
+`not__`:
+
+    ?not__field=value
+
+(_New in AWX 1.4_) By default, all query string filters are AND'ed together, so
+only the results matching *all* filters will be returned.  To combine results
+matching *any* one of multiple criteria, prefix each query string parameter
+with `or__`:
+
+    ?or__field=value&or__field=othervalue
+    ?or__not__field=value&or__field=othervalue
+
+Field lookups may also be used for more advanced queries, by appending the
+lookup to the field name:
+
+    ?field__lookup=value
+
+The following field lookups are supported:
+
+* `exact`: Exact match (default lookup if not specified).
+* `iexact`: Case-insensitive version of `exact`.
+* `contains`: Field contains value.
+* `icontains`: Case-insensitive version of `contains`.
+* `startswith`: Field starts with value.
+* `istartswith`: Case-insensitive version of `startswith`.
+* `endswith`: Field ends with value.
+* `iendswith`: Case-insensitive version of `endswith`.
+* `regex`: Field matches the given regular expression.
+* `iregex`: Case-insensitive version of `regex`.
+* `gt`: Greater than comparison.
+* `gte`: Greater than or equal to comparison.
+* `lt`: Less than comparison.
+* `lte`: Less than or equal to comparison.
+* `isnull`: Check whether the given field or related object is null; expects a
+  boolean value.
+* `in`: Check whether the given field's value is present in the list provided;
+  expects a list of items.
+
+Boolean values may be specified as `True` or `1` for true, `False` or `0` for
+false (both case-insensitive).
+
+Null values may be specified as `None` or `Null` (both case-insensitive),
+though it is preferred to use the `isnull` lookup to explicitly check for null
+values.
+
+Lists (for the `in` lookup) may be specified as a comma-separated list of
+values.

awx/api/templates/api/_new_in_awx.md

@@ -0,0 +1,2 @@
+{% if new_in_13 %}> _New in AWX 1.3_{% endif %}
+{% if new_in_14 %}> _New in AWX 1.4_{% endif %}

awx/api/templates/api/_result_fields_common.md

@@ -0,0 +1,6 @@
+{% for fn, fm in serializer_fields.items %}{% spaceless %}
+{% if not write_only or not fm.read_only %}
+* `{{ fn }}`: {{ fm.help_text|capfirst }} ({{ fm.type }}{% if fm.required %}, required{% endif %}{% if fm.read_only %}, read-only{% endif %})
+{% endif %}
+{% endspaceless %}
+{% endfor %}

awx/api/templates/api/api_root_view.md

@@ -0,0 +1,4 @@
+The root of the AWX REST API.
+
+Make a GET request to this resource to obtain information about the available
+API versions.

awx/api/templates/api/api_v1_config_view.md

@@ -0,0 +1,12 @@
+Site configuration settings and general information.
+
+Make a GET request to this resource to retrieve the configuration containing
+the following fields (some fields may not be visible to all users):
+
+* `project_base_dir`: Path on the server where projects and playbooks are \
+  stored.
+* `project_local_paths`: List of directories beneath `project_base_dir` to
+  use when creating/editing a project.
+* `time_zone`: The configured time zone for the server.
+* `license_info`: Information about the current license.
+* `version`: Version of AWX package installed.

awx/api/templates/api/api_v1_root_view.md

@@ -0,0 +1,4 @@
+Version 1 of the AWX REST API.
+
+Make a GET request to this resource to obtain a list of all child resources
+available via the API.

awx/api/templates/api/api_view.md

@@ -0,0 +1,3 @@
+{{ docstring }}
+
+{% include "api/_new_in_awx.md" %}

awx/api/templates/api/auth_token_view.md

@@ -0,0 +1,31 @@
+Make a POST request to this resource with `username` and `password` fields to
+obtain an authentication token to use for subsequent requests.
+
+Example JSON to POST (content type is `application/json`):
+
+    {"username": "user", "password": "my pass"}
+
+Example form data to post (content type is `application/x-www-form-urlencoded`):
+
+    username=user&password=my%20pass
+
+If the username and password provided are valid, the response will contain a
+`token` field with the authentication token to use and an `expires` field with
+the timestamp when the token will expire:
+
+    {
+        "token": "8f17825cf08a7efea124f2638f3896f6637f8745",
+        "expires": "2013-09-05T21:46:35.729Z"
+    }
+
+Otherwise, the response will indicate the error that occurred and return a 4xx
+status code.
+
+For subsequent requests, pass the token via the HTTP `Authorization` request
+header:
+
+    Authorization: Token 8f17825cf08a7efea124f2638f3896f6637f8745
+
+Each request that uses the token for authentication will refresh its expiration
+timestamp and keep it from expiring.  A token only expires when it is not used
+for the configured timeout interval (default 1800 seconds).

awx/api/templates/api/base_variable_data.md

@@ -0,0 +1,9 @@
+# Retrieve {{ model_verbose_name|title }} Variable Data:
+
+Make a GET request to this resource to retrieve all variables defined for this
+{{ model_verbose_name }}.
+
+# Update {{ model_verbose_name|title }} Variable Data:
+
+Make a PUT request to this resource to update variables defined for this
+{{ model_verbose_name }}.

awx/api/templates/api/group_all_hosts_list.md

@@ -0,0 +1,7 @@
+# List All {{ model_verbose_name_plural|title }} for this {{ parent_model_verbose_name|title }}:
+
+Make a GET request to this resource to retrieve a list of all
+{{ model_verbose_name_plural }} directly or indirectly belonging to this
+{{ parent_model_verbose_name }}.
+
+{% include "api/_list_common.md" %}

awx/api/templates/api/group_potential_children_list.md

@@ -0,0 +1,9 @@
+# List Potential Child Groups for this {{ parent_model_verbose_name|title }}:
+
+Make a GET request to this resource to retrieve a list of
+{{ model_verbose_name_plural }} available to be added as children of the
+current {{ parent_model_verbose_name }}.
+
+{% include "api/_list_common.md" %}
+
+{% include "api/_new_in_awx.md" %}

awx/api/templates/api/host_all_groups_list.md

@@ -0,0 +1,7 @@
+# List All {{ model_verbose_name_plural|title }} for this {{ parent_model_verbose_name|title }}:
+
+Make a GET request to this resource to retrieve a list of all
+{{ model_verbose_name_plural }} of which the selected
+{{ parent_model_verbose_name }} is directly or indirectly a member.
+
+{% include "api/_list_common.md" %}

awx/api/templates/api/inventory_root_groups_list.md

@@ -0,0 +1,7 @@
+# List Root {{ model_verbose_name_plural|title }} for this {{ parent_model_verbose_name|title }}:
+
+Make a GET request to this resource to retrieve a list of root (top-level)
+{{ model_verbose_name_plural }} associated with this
+{{ parent_model_verbose_name }}.
+
+{% include "api/_list_common.md" %}

awx/api/templates/api/inventory_script_view.md

@@ -0,0 +1,31 @@
+Generate inventory group and host data as needed for an inventory script.
+
+Refer to [External Inventory Scripts](http://www.ansibleworks.com/docs/api.html#external-inventory-scripts)
+for more information on inventory scripts.
+
+## List Response
+
+Make a GET request to this resource without query parameters to retrieve a JSON
+object containing groups, including the hosts, children and variables for each
+group.  The response data is equivalent to that returned by passing the
+`--list` argument to an inventory script.
+
+_(New in AWX 1.3)_ Specify a query string of `?hostvars=1` to retrieve the JSON
+object above including all host variables.  The `['_meta']['hostvars']` object
+in the response contains an entry for each host with its variables.  This
+response format can be used with Ansible 1.3 and later to avoid making a
+separate API request for each host.  Refer to
+[Tuning the External Inventory Script](http://www.ansibleworks.com/docs/api.html#tuning-the-external-inventory-script)
+for more information on this feature.
+
+_(New in AWX 1.4)_ By default, the inventory script will only return hosts that
+are enabled in the inventory.  This feature allows disabled hosts to be skipped
+when running jobs without removing them from the inventory.  Specify a query
+string of `?all=1` to return all hosts, including disabled ones.
+
+## Host Response
+
+Make a GET request to this resource with a query string similar to
+`?host=HOSTNAME` to retrieve a JSON object containing host variables for the
+specified host.  The response data is equivalent to that returned by passing
+the `--host HOSTNAME` argument to an inventory script.

awx/api/templates/api/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 "api/_new_in_awx.md" %}

awx/api/templates/api/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 "api/_new_in_awx.md" %}

awx/api/templates/api/inventory_tree_view.md

@@ -0,0 +1,15 @@
+# Group Tree for this {{ model_verbose_name|title }}:
+
+Make a GET request to this resource to retrieve a hierarchical view of groups
+associated with the selected {{ model_verbose_name }}.
+
+The resulting data structure contains a list of root groups, with each group
+also containing a list of its children.
+
+## Results
+
+Each group data structure includes the following fields:
+
+{% include "api/_result_fields_common.md" %}
+
+{% include "api/_new_in_awx.md" %}

awx/api/templates/api/job_cancel.md

@@ -0,0 +1,10 @@
+# Cancel Job
+
+Make a GET request to this resource to determine if the job can be cancelled.
+The response will include the following field:
+
+* `can_cancel`: Indicates whether this job can be canceled (boolean, read-only)
+
+Make a POST request to this resource to cancel a pending or running job.  The
+response status code will be 202 if successful, or 405 if the job cannot be
+canceled.

awx/api/templates/api/job_list.md

@@ -0,0 +1,5 @@
+{% include "api/list_create_api_view.md" %}
+
+If the `job_template` field is specified, any fields not explicitly provided
+for the new job (except `name` and `description`) will use the default values
+from the job template.

awx/api/templates/api/job_start.md

@@ -0,0 +1,15 @@
+# Start Job
+
+Make a GET request to this resource to determine if the job can be started and
+whether any passwords are required to start the job.  The response will include
+the following fields:
+
+* `can_start`: Flag indicating if this job can be started (boolean, read-only)
+* `passwords_needed_to_start`: Password names required to start the job (array, read-only)
+
+Make a POST request to this resource to start the job.  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 job cannot be
+started, a 405 status code will be returned.

awx/api/templates/api/job_template_callback.md

@@ -0,0 +1,33 @@
+The job template callback allows for empheral hosts to launch a new job.
+
+Configure a host to POST to this resource, passing the `host_config_key`
+parameter, to start a new job limited to only the requesting host.  In the
+examples below, replace the `N` parameter with the `id` of the job template
+and the `HOST_CONFIG_KEY` with the `host_config_key` associated with the
+job template.
+
+For example, using curl:
+
+    curl --data-urlencode host_config_key=HOST_CONFIG_KEY http://server/api/v1/job_templates/N/callback/
+
+Or using wget:
+
+    wget -O /dev/null --post-data="host_config_key=HOST_CONFIG_KEY" http://server/api/v1/job_templates/N/callback/
+    
+The response will return status 202 if the request is valid, 403 for an
+invalid host config key, or 400 if the host cannot be determined from the
+address making the request.
+
+A GET request may be used to verify that the correct host will be selected.
+This request must authenticate as a valid user with permission to edit the
+job template.  For example:
+
+    curl http://user:password@server/api/v1/job_templates/N/callback/
+
+The response will include the host config key as well as the host name(s)
+that would match the request:
+
+    {
+        "host_config_key": "HOST_CONFIG_KEY",
+        "matching_hosts": ["hostname"]
+    }

awx/api/templates/api/job_template_jobs_list.md

@@ -0,0 +1,6 @@
+{% extends "api/sub_list_create_api_view.md" %}
+
+{% block post_create %}
+Any fields not explicitly provided for the new job (except `name` and
+`description`) will use the default values from the job template.
+{% endblock %}

awx/api/templates/api/list_api_view.md

@@ -0,0 +1,8 @@
+# List {{ model_verbose_name_plural|title }}:
+
+Make a GET request to this resource to retrieve the list of
+{{ model_verbose_name_plural }}.
+
+{% include "api/_list_common.md" %}
+
+{% include "api/_new_in_awx.md" %}

awx/api/templates/api/list_create_api_view.md

@@ -0,0 +1,12 @@
+{% include "api/list_api_view.md" %}
+
+# Create {{ model_verbose_name_plural|title }}:
+
+Make a POST request to this resource with the following {{ model_verbose_name }}
+fields to create a new {{ model_verbose_name }}:
+
+{% with write_only=1 %}
+{% include "api/_result_fields_common.md" %}
+{% endwith %}
+
+{% include "api/_new_in_awx.md" %}

awx/api/templates/api/organization_admins_list.md

@@ -0,0 +1,3 @@
+{% with model_verbose_name="admin user" model_verbose_name_plural="admin users" %}
+{% include "api/sub_list_create_api_view.md" %}
+{% endwith %}

awx/api/templates/api/project_playbooks.md

@@ -0,0 +1,4 @@
+# Retrieve {{ model_verbose_name|title }} Playbooks:
+
+Make GET request to this resource to retrieve a list of playbooks available
+for this {{ model_verbose_name }}.

awx/api/templates/api/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 "api/_new_in_awx.md" %}

awx/api/templates/api/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 "api/_new_in_awx.md" %}

awx/api/templates/api/retrieve_api_view.md

@@ -0,0 +1,9 @@
+# Retrieve {{ model_verbose_name|title }}:
+
+Make GET request to this resource to retrieve a single {{ model_verbose_name }}
+record containing the following fields:
+
+{% include "api/_result_fields_common.md" %}
+
+{% include "api/_new_in_awx.md" %}
+

awx/api/templates/api/retrieve_update_api_view.md

@@ -0,0 +1,16 @@
+{% include "api/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 "api/_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 "api/_new_in_awx.md" %}

awx/api/templates/api/retrieve_update_destroy_api_view.md

@@ -0,0 +1,20 @@
+{% include "api/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 "api/_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.
+
+# Delete {{ model_verbose_name|title }}:
+
+Make a DELETE request to this resource to delete this {{ model_verbose_name }}.
+
+{% include "api/_new_in_awx.md" %}

awx/api/templates/api/sub_list_api_view.md

@@ -0,0 +1,9 @@
+# List {{ model_verbose_name_plural|title }} for this {{ parent_model_verbose_name|title }}:
+
+Make a GET request to this resource to retrieve a list of
+{{ model_verbose_name_plural }} associated with the selected
+{{ parent_model_verbose_name }}.
+
+{% include "api/_list_common.md" %}
+
+{% include "api/_new_in_awx.md" %}

awx/api/templates/api/sub_list_create_api_view.md

@@ -0,0 +1,39 @@
+{% include "api/sub_list_api_view.md" %}
+
+# Create {{ model_verbose_name_plural|title }} for this {{ parent_model_verbose_name|title }}:
+
+Make a POST request to this resource with the following {{ model_verbose_name }}
+fields to create a new {{ model_verbose_name }} associated with this
+{{ parent_model_verbose_name }}.
+
+{% with write_only=1 %}
+{% include "api/_result_fields_common.md" %}
+{% endwith %}
+
+{% block post_create %}{% endblock %}
+
+{% if parent_key %}
+# Remove {{ parent_model_verbose_name|title }} {{ model_verbose_name_plural|title }}:
+
+Make a POST request to this resource with `id` and `disassociate` fields to
+delete the associated {{ model_verbose_name }}.
+
+    {
+        "id": 123,
+        "disassociate": true
+    }
+
+{% else %}
+# Add {{ model_verbose_name_plural|title }} for this {{ parent_model_verbose_name|title }}:
+
+Make a POST request to this resource with only an `id` field to associate an
+existing {{ model_verbose_name }} with this {{ parent_model_verbose_name }}.
+
+# Remove {{ model_verbose_name_plural|title }} from this {{ parent_model_verbose_name|title }}:
+
+Make a POST request to this resource with `id` and `disassociate` fields to
+remove the {{ model_verbose_name }} from this {{ parent_model_verbose_name }}
+without deleting the {{ model_verbose_name }}.
+{% endif %}
+
+{% include "api/_new_in_awx.md" %}

awx/api/templates/api/user_admin_of_organizations_list.md

@@ -0,0 +1,7 @@
+# List {{ model_verbose_name_plural|title }} Administered by this {{ parent_model_verbose_name|title }}:
+
+Make a GET request to this resource to retrieve a list of
+{{ model_verbose_name_plural }} of which the selected
+{{ parent_model_verbose_name }} is an admin.
+
+{% include "api/_list_common.md" %}

awx/api/templates/api/user_me_list.md

@@ -0,0 +1,7 @@
+Make a GET request to retrieve user information about the current user.
+
+One result should be returned containing the following fields:
+
+{% include "api/_result_fields_common.md" %}
+
+Use the primary URL for the user (/api/v1/users/N/) to modify the user.