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: For all all newly created Groups on Enterprise Plan For all newly created Organizations on other plans with access to the Snyk API	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-tags-tool

• scm-contributors-count

• 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