Search Audit Logs (Group and Org) v1 API to GA REST Audit logs API migration guide
Last updated
Last updated
More information
Snyk privacy policy© 2024 Snyk Limited | All product and company names and logos are trademarks of their respective owners.
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 |
|---|---|---|
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",
}
}
```
(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.