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/:

_images/ui-api-browser.png

You can navigate the interface and drill down to list views, for example:

_images/ui-api-browser-playbooks.png

You can also see what a detailed view looks like by querying a specific object id:

_images/ui-api-browser-playbook.png

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:

_images/database-model.png

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.