| Table of Contents |
|---|
Introduction
Open-AudIT is implementing a JSON Restful API to be used both in the web interface and via JSON requests.
NOTE - This API is not ready for a full release as yet and items below are subject to change.As at 1.12.6 though, this is how it stands. We don't envision big breaking changes going forward, but until such time as we give the official "released" stamp of approval, items are subject to (and indeed WILL) change.
NOTE - This page is incomplete and is being updated as we work towards a released verion of the API.
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/URI format and supply some additional actions.
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 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..
...
To request a different version of the API (currently only v1 exists), use the url /api/{version}/devices or /v1/devices.
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 restful 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.
Routing Table
The default action if notihng matches below is to return a collection of items.
* Not all routes are available on or apply to all endpoints.
** Actions ending in _form are for web form input
You cannot delete a default org, location or script.
| 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> / or list | collection | |||||
...