Macros API#
The web API provides methods for accessing and creating search macros, which are mappings of a short string to a longer string which is expanded during the parse phase of a search.
The SearchMacro structure#
The web server returns macros in a JSON struct which is also used to update fields. Note that when sending a struct to update a macro, not all fields are updated (it is not possible to change the LastUpdated field manually, for instance). The fields are largely self-explanatory but are explained here for precision:
ID: a unique integer representing this macro
UID: the macro owner’s integer UID
GIDs: a list of integer group IDs which are allowed to access the macro
Name: the short name of the macro as typed in a search query
Expansion: the string to which the macro expands
LastUpdated: the time at which this macro was most recently modified
Synced: (internal use only)
Listing macros#
To get a list of all macros belonging to the current user, do a GET on /api/macros
. The result will look like this:
[{"ID":1,"UID":1,"GIDs":null,"Name":"FOO","Expansion":"grep foo","LastUpdated":"2018-10-31T20:56:24.629561628Z","Synced":true}]
In this example, the user with UID 1 has one macro named “FOO” which expands to the string “grep foo”. The macro ID is 1, which can be used in other APIs.
Getting macros by user ID#
Admin users can retrieve a list of a specific user’s macros by performing a GET on /api/users/{uid}/macros
, replacing {uid}
with the desired user ID. Non-admin users can use this API to retrieve their own macros.
Getting macros by group ID#
Admin users or members of a group can retrieve a list of macros to which a specified group has access by performing a GET on /api/groups/{gid}/macros
.
Getting all macros#
Admin users can retrieve a list of all macros on the system by performing a GET on /api/macros/all
.
Retrieving a specific macro#
The structure for a specific macro may be retrieved by doing a GET on /api/macros/{id}
, replacing {id}
with the macro ID. For instance, a GET on /api/macros/1
returns the following:
{"ID":1,"UID":1,"GIDs":null,"Name":"FOO","Expansion":"grep foo","LastUpdated":"2018-10-31T20:56:24.629561628Z","Synced":true}
Creating a new macro#
New macros may be created via POST to /api/macros
. The body of the request should contain the Name and Expansion fields and (optionally) the GIDs field, as shown below:
{"GIDs": [1, 2], "Name": "TEST", "Expansion": "grep test | count"}
A successful creation will return the ID of the new macro; in this example the new ID was 2, so a GET on /api/macros/2
yields the full body of the new macro:
{"ID":2,"UID":1,"GIDs":null,"Name":"TEST","Expansion":"grep test | count","LastUpdated":"2018-10-31T21:05:34.231426316Z","Synced":true}
Updating a macro#
Updating a macro may be done by PUT to /api/macros/{id}
using the same body format as a creation; note that for safety, it is best to populate the GIDs, Name, and Expansion fields every time even if no changes are made.
A successful update returns HTTP 200 and the updated macro in the body.
Deleting a macro#
Macro deletion is performed via a DELETE on /api/macros/{id}
. This returns HTTP 200 upon success.