c2ce3724a7
This updates the README and moves "how ara works" as well as "what ara looks like" from the FAQs to the README where they are more relevant. Change-Id: Ic928b23802b393e6775b54b3e6c51982758e79d6
2.0 KiB
API Documentation
The API documentation is a work in progress.
Built-in API browser interface
ARA ships with a helpful interface to navigate the API directly from your favorite web browser.
For example, if you run ara-manage runserver, this
interface would be available at
http://127.0.0.1:8000/api/v1/:
You can navigate the interface and drill down to list views, for example:
You can also see what a detailed view looks like by querying a specific object id:
Alternatively, you may also find an up-to-date live demonstration of
the API at https://api.demo.recordsansible.org.
Relationship between objects
The relationship between objects in the API should be straightforward with an understanding of how Ansible playbooks are executed.
Generally speaking, the data is organized in the following fashion:
labels
|
Playbook -> Play -> Task -> Result <- Host
| | | |
file file content facts- Every object is associated to a playbook (except labels which are applied to playbooks)
- In a playbook you have plays
- In plays you have tasks
- In tasks you have results
- Results have a relationship to their parent task and the host the task ran on
- Files are only associated to a playbook but tasks have a reference to the file they were executed from
- Records (provided by
ara_record) are only associated to a playbook
Additional fields may only be available in the detailed views. For example:
- Playbooks arguments with
/api/v1/playbooks/<id> - Hosts facts with
/api/v1/hosts/<id> - Results content with
/api/v1/results/<id> - Files content with
/api/v1/files/<id>
ARA ships with two built-in API clients to help you get started. You
can learn more about those clients in api-usage:Using ARA API clients.