Introduction
Open-AudIT is implementing a JSON Restful API to be used both in the web interface and via JSON requests.
Open-AudIT's API
Open-AudIT is basing it's API on http://jsonapi.org with the intention of providing simple and intuitive access in a manner familiar to developers.
In addition to this API, the web interface will use the same request format and supply some additional actions.
Access Model
The API is using our new model of access. Instead of a user <-> group model, we're using user <-> organisation.
The Endpoints
At present we have endpoints for:
devices - The devices, bg surprise.
orgs - The organisations setup within.
networks - The networks detected by Open-AudIT. This also doubles as our "blessed subnets" list.
Collections to be introduced
Locations, scripts, users, discoveries, config, additional fields, groups queries and more are planned. Basically everything that is possible to move to the new model inside Open-AudIT will be.
Options
Format
Using the format option is useful when using a web browser but you wish to see the result in JSON format. Adding format=json achieves this. Normally a web browser will set it's accept header to html, so in that case we return the rendered page. Using an API to retrieve JSON you should set the accept header to contain the string "json". That might be "json/application" or whatever you like. You can over ride this by providing the format option in the URL..
Action
When using the API the default action is determined according to the format and URL. You can override this by providing the 'action' option in the URL. An example of this is when creating a new item. You would normally use POST to /item but in the case of a web user, you need a web form to be able to fill out the item details. In that case there is no facility for this in a typical JSON restul API. We work around this by providing action=create in a GET request for the URL. IE - http://{server}/open-audit/index.php/networks?action=create.
Sort
Current
GroupBy
Limit
Offset
Properties
Filter
Version
End Points
All endpoints URLs are of the format http://{server}/open-audit/index.php/{endpoint}
Devices
| Type | Endpoint | ||
|---|---|---|---|
| GET | /devices | Return a collection of devices with the default set of columns from the system table (system.id, system.icon, system.type, system.name, system.domain, system.ip, system.description, system.os_family, system.status) | |
| GET | /devices/{id} | Return an individual devices details. | |
| GET | /devices?subresource={subresource name} | To return all items in a subresource for a collection of devices. If you wanted all software you would use http://{server}/open-audit/index.php/devices?sub_resource=software | |
| GET | /devices/{id}?subresource={subresource name} | To return all items in a subresource for a specific device. | |
| GET | /devices?sub_resource={subresource name}&sub_resource_id={subresource id} | To return a specific item in a subresource for a collection of devices - not especially useful. You would more likely use the below (request a subresource items from a specific device) | |
| GET | /devices{id}?sub_resource={subresource name}&sub_resource_id={subresource id} | To return a specific subresource item for a specific device. |
Networks
Orgs