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 its 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 override this by providing the format option in the URL..
We tend to use the Google Chrome extension called Postman for testing actual restful queries. You might like to install and test with that. http://www.getpostman.com.
format={json}
Sort
To sort by a database column, user "sort={attribute}". To reverse sort, insert a minus, thus "sort=-{attribute}".
sort=[-]{attribute}
Current
By default, only attributes with "current=y" are retrieved. To override this, set current as below.
current={y|n|all}
GroupBy
groupby={attribute}
Limit
When requesting JSON, by default no limit is set. When requesting screen display, limit is set to 1000 by default.
limit={int}
Offset
The offset is the count of devices you wish to return data from.
offset={int}
Properties
Requested properties should be in a comma separated list.
properties={attribute 1},{attribute 2},{attribute 3}
Filter
To filter by a property value, use the property name. Operators that should precede the value are !=, >, >=, <, <=, 'like' and '!like'. If no operator is specified, the default is =.
{attribute}=[operator]{value}
Include
When requesting the details fo a resource (a device), if the request is JSON based only the 'system' table will be returned. NOT all the related tables. There will be links for these tables in the data->links section. If you would like the system tabel AND the bios table (for example) in a JSON request, you can use the 'include' keyword. An example would be a GET request with accept header as JSON to http://server/open-audit/index.php/devices?include=bios. For a HTML (web browser) formatted request, by default all related tables are included so the web page can render the device details as it has always done. When using include, you can use the keyword 'all' to retrieve all tables that contain related information.
include={sub_resource}
Version
To request a different version of the API (currently only v1 exists), use the url /api/{version}/devices or /v1/devices.
Routing Table
* Not all routes are available on or apply to all endpoints.
** Actions ending in _form are for web form input
| Request Method | id | action | sub_resource | sub_resource_id | Resulting Action | Notes | URL Example |
|---|---|---|---|---|---|---|---|
| GET | N | <empty> | collection | /devices | |||
| GET | N | create | create_form | /devices?action=create | |||
| GET | Y/N | create | Y | sub_resource_create_form | /devices?action=create&sub_resource=credentials | ||
| GET | N | import | import_form | /devices?action=import | |||
| GET | Y | read | /devices/{id} | ||||
| GET | Y | update | update_form | /devices/{id}?action=update | |||
| GET | Y | download | download | /scripts/{id}?action=download | |||
| GET | N | update | bulk_update_form | Should provide attribute "ids" which is a comma separated list of ID's upon which to bulk update. | /devices?action=update&ids=1,2,3,4 | ||
| POST | N | create | /devices | ||||
| POST | N | import | import | /devices?action=import | |||
| POST / PUT / PATCH | Y | <empty> | update | /devices/{id}?action=update | |||
| POST | Y | Y | sub_resource_create | /devices/{id}?sub_resource=credential | |||
| DELETE | Y | N | delete | /scripts/{id} | |||
| DELETE | Y | Y | Y | sub_resource_delete | /devices/{id}/credential/{sub_resource_id} | ||
| ALL | <empty> / list | collection | |||||
Devices
Examples of retrieving data
| HTTP Verb | Accept | URL | Result | Example Response |
|---|---|---|---|---|
| GET | JSON | /devices | Get a list of all devices. | devices.json |
| GET | JSON | /devices?properties=system.id,system.name,system.type,system.serial | Get a list of devcies with the data id, name, type and serial | devices_properties.json |
| GET | JSON | /devices/8 | Get the system table of device with id = 8. | devices_8.json |
| GET | JSON | /devices/8?include=bios | Get the system table and bios table for device with ID = 8. | devices_8_include_bios.json |
Example of updating a device
| HTTP Verb | Accept | URL | Data | Result | Example Response |
|---|---|---|---|---|---|
| PATCH | JSON | /devices/8 | {
"data": {
"type" : "devices",
"id" : 8,
"attributes" : {
"description" : "my HP"
}
}
}
| Update the description of the device with ID = 8. | devices_8_patch_description.json |
Device sub_resource Names
NAME | NAME | NAME |
|---|---|---|
audit_log | netstat | service |