...
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.
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.
...
The API is using our new model of access. Instead of a user <-> group model, we're using user <-> organisation. If you're having trouble at this early stage, just use the 'administrator' or 'open-audit_enterprise' account(s). We have not created the GUI screens to associate a user to an organisation as yet. If you wish to use another account you could run the below SQL directly to create the association:
| Code Block |
|---|
INSERT INTO oa_user_org VALUES (NULL, $user_id, $org_id, 10, ''); |
Where your new $user_id and $org_id can be found in the Open-AudIT web interface.
The Endpoints
At present we have endpoints for:
...
Collections to be introduced
Locations, scripts, files, 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.
...
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 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 over ride 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.
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 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. The default action if noting matches below is to return a collection of items.
| Request | Name | ID | Result | Implemented |
|---|---|---|---|---|
| GET | Return a collection of items | Y | ||
| ANY | list | Return a collection of items. | Y | |
| GET | create | Show a HTML form to create a new item. | N | |
| GET | import | N | ||
| GET | read | Y | Show the details of an item. | Y |
| GET | edit | Y | Show a form to edit an item's details. | Y |
| POST / PUT / PATCH | Y | Update an item's details. | Y | |
| DELETE | Y | Delete an item. | Y | |
Sort
To sort by a database column, user "sort={attribute}". To reverse sort, insert a minus, thus "sort=-{attribute}".
...