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://demo.recordsansible.org
.
Relationship between objects¶
Here’s a high level overview of how data is generally organized:
Label Record (ara_record) LatestHost
\ / /
Playbook -> Play -> Task -> Result <- Host
\ / | |
\ / Content Facts
\ File /
|
Content
Every object except labels and LatestHost are associated to a parent playbook
Labels are applied on a playbook while a LatestHost references a specific Host
Records have a key, a value and a type provided by ara_record
In a playbook there are plays
In a play there are tasks
In a task there are results
Results have a relation to their parent task and the host the task ran on
Results have content with data returned by Ansible for a task on a host
Hosts have stats provided by Ansible and facts (if they have been set or gathered)
A LatestHost relation keeps track of the last playbook a host name was involved in
Playbooks and Tasks both have a path and a reference to a File
A file has content compressed and uniquely stored, hashed by sha1
These relationships are also represented in the database model:

Tip
Open the image above in a new tab to see it in full resolution.
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>
or/api/v1/latesthosts
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 Using ARA API clients.