Search Audit Logs (Group and Org) v1 API to GA REST Audit logs API migration guide
What’s new in the REST Search Audit Logs API?
Based on OpenAPI specifications, the Snyk REST API is designed to provide a consistent, friendly, and easy-to-use API framework that introduces some major improvements. The benefits of the new APIs include:
Consistent versioning
Improved performance
The Search Audit Logs REST API deprecates offset-based pagination in favour of more performant and consistent cursor-based pagination. Our v1 APIs get slower the higher your page offset becomes and will eventually time out at very high page counts. We’ve improved this considerably in our REST API by using a cursor-based approach that consistently returns results at greater speeds regardless of page count.
As well as performance improvements we have also improved filtering capabilities, allowing users to provide multiple include or exclude events for finer-tuned filtering. In a addition to this, the API was only capable of searching for logs within a minimum time-frame of 24 hours, we’ve improved this with higher granularity time stamps RFC3339, which allows users to search within windows of minutes on a given day.
`api.access` logs are now excluded by default on all search queries unless explicitly provided as part of the `events` parameter. These are typically high-volume low-information logs that are superseded by our explicit action logs, e.g. group.create. Explicit action logs will contain richer contextual information for an action and should be favoured in all cases.
Here is what you could use in the v1 endpoints, and their GA REST equivalents:
| v1 Group and Org Search Audit Logs | GA REST API | Notes |
|---|---|---|
(query) from (YYYY-MM-DD) | (query) from (RFC3339) | Time format changed |
(query) to (YYYY-MM-DD) | (query) to (RFC3339) | Time format changed. |
(query) page (Number) | (query) cursor (string) | |
(query) sortOrder | unchanged | |
(body) filters.userId (string) | (query) user_id (string) | Moved from request body to query parameter. |
(body) filters.email (string) | deprecated | Based on user feedback, this was removed |
(body) filters.event (string) | (query) events (comma-separated list) | Parameter name change and moved into query. Supports multiple values. |
(body) filters.excludeEvent (string) | (query) exclude_events (comma-separated list) | Parameter name change and moved into query. Supports multiple values. |
(body) filters.projectId (string) | (query) project_id (string) | Moved from request body to query parameter. |
Response
Audit log event payloads have not changed as part of the REST migration, however, the structure of the response is different to conform to our standardised JSON API responses.
The V1 response is returned as an array, e.g.
```
[
{
"groupId": "4a18d42f-0706-4ad0-b127-24078731fbea",
"orgId": "4a18d42f-0706-4ad0-b127-24078731fbea",
"userId": "4a18d42f-0706-4ad0-b127-24078731fbea",
"projectId": null,
"event": "group.edit",
"content": {
"before": {
"name": "Group Previous Name"
},
"after": {
"name": "Group Current Name"
}
},
"created": "2017-04-11T21:00:00.000Z"
}
]
```
The REST response will contain the same event payload information, however, it will be in the following format:
```
{
"data": {
"items": [
{
"groupId": "4a18d42f-0706-4ad0-b127-24078731fbea",
"orgId": "4a18d42f-0706-4ad0-b127-24078731fbea",
"userId": "4a18d42f-0706-4ad0-b127-24078731fbea",
"projectId": null,
"event": "group.edit",
"content": {
"before": {
"name": "Group Previous Name"
},
"after": {
"name": "Group Current Name"
}
},
"created": "2017-04-11T21:00:00.000Z"
}
],
},
"jsonapi": {
"version": "1.0"
},
"links": {
"next": "https://example.com/api/resource",
}
}
```
Last updated