List all Projects V1 API to REST API migration guide (completed migration)
End of life
On June 22, 2023, Snyk announced the plan to sunset the List all projects V1 API with end-of-life on December 22, 2023, in favor of the REST List all projects API.
What’s new in the REST Projects 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
Pagination and caching
Improved performance
Client generation
The Projects REST API introduces improved data architecture to facilitate enhanced performance and separation of domains.
Snyk understands that migrating to a new API can be a significant undertaking and wants to support you throughout the process. This comprehensive migration guide is intended to facilitate a seamless transition by providing step-by-step instructions, code examples, and best practices to help you smoothly integrate with the new API.
If you are using the deprecated endpoint, Snyk encourages you to review this migration guide and move all your automations over before Friday, December 22, 2023.
Timeline for migration to the REST API
| Step | Due date | Your Action Items |
|---|---|---|
Announce that List all projects v1 API is now deprecated | June 22, 2023 | Review the current API usage and use and identify where a migration would need to take place |
Migration guide to be published with a detailed comparison between v1 and REST Projects API | June 22, 2023 | Review the migration guide and plan to migrate any existing code and workflows before the final date |
List all projects v1 API will now return 410 Gone:
| June 22, 2023 | No action needed for existing users on Enterprise plan New users should use the REST Projects API for all new integrations
|
Snyk Tools | August 15, 2023 | Customers using Snyk Tools need to upgrade to a version that supports using the REST Projects API instead of v1
Refer to the detailed list included in this guide |
List all projects v1 API documentation removal | September 22, 2023 | No action needed |
End-of-life: All access to List all projects v1 API will result in a 410 Gone response. | December 22, 2023 | Ensure migration has been completed by this time to avoid disruption to automated workflows |
The following Snyk Tools that use the List all projects v1 API have been updated to use the REST List all projects API instead:
snyk-jira-tickets-for-new-vulns: version 5.0.0 or newer
snyk-api-ts-client: version 1.11.1 or newer
snyk-request-manager: version 1.8.1 or newer
backstage-plugin: version 2.0.0 or newer
api-import-tool: version 1.99.0 or newer
snyk-scm-mapper: latest version
pysnyk: version 0.9.8 or newer
snyk-repo-diff: latest version
snyk delta: version 1.9.0 or newer
snyk-issues-to-csv: latest version
snyk-disallow: this tool is now deprecated
snyk-prevent-gh-commit-status: version 2.2.1 or newer
Various CX Tools code samples have been updated
Comparison of v1 to REST Projects API
| V1 /org/:orgId/projects | REST /orgs/:orgId/projects |
|---|---|
org.name | data[i].relationships.organization.links.related - Provides a REST API link to retrieve more data about an organization via REST GET /orgs/:org_id |
org.id | data[i].relationships.organization.data.id - Can also use the provided rest API link to retrieve more data about an organization via REST GET /orgs/:org_id |
name | data[i].attributes.name |
created | data[i].attributes.created |
origin | data[i].attributes.origin |
type | data[i].attributes.type |
readOnly | data[i].attributes.read_only |
testFrequency | data.[i].attributes.settings.recurring_tests.frequency |
totalDependencies | Can be fetched optionally by specifying the meta.latest_dependency_total query parameter |
issueCountBySeverity.low issueCountBySeverity.medium issueCountBySeverity.high issueCountBySeverity.critical | Can be fetched optionally by specifying the meta.latest_issue_counts query parameter |
imageId | Can be fetched from the latest project snapshot via v1 POST org/:orgId/project/:projectId/history |
imageTag | Can be fetched from the latest project snapshot via v1 POST org/:orgId/project/:projectId/history |
imageBaseImage | Can be fetched from the latest project snapshot via v1 POST org/:orgId/project/:projectId/history |
imagePlatform | Can be fetched from the latest project snapshot via v1 POST org/:orgId/project/:projectId/history |
imageCluster | Data[i].target.data.id - Use the expand parameter to expand this relationship or make a separate API call to REST Targets API to get a matching target and grab the cluster data from there. |
remoteRepoUrl | Data[i].relationships.target.data.attributes.url - Use the expand parameter to expand the target relationship |
lastTestedDate | meta.latest_dependency_total.updated_at or meta.latest_issue_counts.updated_at - can be fetched optionally by specifying the meta.latest_issue_counts or meta.latest_dependency_total query parameter |
owner.id owner.name owner.username owner.email | data[i].relationships.owner.links.related - provides REST API link to retrieve more data about importing user via REST GET /orgs/:org_id/users/:id (beta) |
browseUrl | N/A - can be constructed using organization slug and project ID https://app.snyk.io/org/:orgSlug/project/:projectId |
importingUser.id importingUser.name importingUser.username importingUser.email | data.[i]relationships.importer.data.id, data[i]relationships.importer.links.related Additionally provides REST API link to retrieve more data about importing user via REST GET /orgs/:org_id/users/:id (beta) |
isMonitored | data[i].attributes.status |
branch | data[i].attributes.target_reference |
targetReference | data[i].attributes.target_reference |
"tags": [ { "key": "example-tag-key", "value": "example-tag-value" } ] | data[i].attributes.tags[ { "key": "example-tag-key", "value": "example-tag-value" } ] |
attributes.criticality
| data[i].attributes.business_criticality |
attributes.environment | data[i].attributes.environment |
attributes.lifecycle | data[i].attributes.lifecycle |
Filters
Filter by name If supplied, only Projects that have a name that starts with this value will be returned
| Filter: names Return projects that match the provided names. | Use REST Targets API to find matching Targets and then filter the Projects based on the target IDs.
For filtering without additional API calls, use the expand parameter on REST List all projects for an org to expand the targets relationship and return all relevant target data at the same time |
Filter by tags | Filter: tags Return projects that match all the provided tags
| Supported from version 2023-02-15 and up |
Filter by attributes | Filter: business_criticality, environment and lifecycle | Supported from version 2023-02-15 and up |
Last updated