rest-issues-experimental-api-to-ga-api-migration-guide.md

REST Issues experimental API to GA API migration guide

{% hint style="info" %} Important information about Experimental APIs

An experimental endpoint should be considered unstable and regarded as a tech preview. Experimental versions may introduce breaking changes and may be discontinued at any time. {% endhint %}

What's new in the GA REST Issues API?

{% hint style="info" %} GA REST Issues API documentation /groups/{group_id}/issues and /orgs/{org_id}/issues. {% endhint %}

This version of the API delivers:

• Consistency: Improved performance and reliability of the REST Issues API
• Depth: detailed representations for Open Source packages and fixes
• Flexibility: new filters for tailored API responses
• Usability: improved pagination and response management, simplifying the API interaction

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.

Comparison of experimental vs GA API

{% hint style="info" %} Mapping experimental API issues to GA API issues

One of the main differences you will see in the table below is that the format of the ID for an issue changes from URI format (consists of key & scan_item.id) in the Experimental API to UUID in the GA API. To match an issue in the experimental api response to the same issue in the GA API response you can use key and the scan_item.id. Note that scan_item is part of the relationships block and key is part of the attributes block. {% endhint %}

Fields	Experimental	GA
classes	Present	No change
coordinates	Only available for cloud issues	Available for cloud and SCA issues and has new fixability fields.
coordinates.is_fixable_manually coordinates.is_fixable_snyk coordinates.is_fixable_upstream coordinates.is_patchable coordinates.is_pinnable coordinates.is_upgradeable	Not present	Newly introduced fixability data
coordinates.reachability	Not present	Newly introduced
coordinates.remedies	Present	No change
representations	Present	New fields
representations.resourcePath	Present	No change
respresentations.dependencyChain	Present	Removed in favor of representations.dependency
representations.dependency	Not present	Newly introduced replaces representations. dependencyChain
representations.dependency .package_name representations.dependency. package_version	Not present	Newly introduced as part of represenations.dependency
cloud_resource	Present	No change
sourceLocation	Present	No change
created_at	Present	No change
description		No change
effective_severity_level	Present	No change
ignored	Present	No change
key	Present	No change
priority	Present	Removed and replaced with risk
priority.factors	Present	Replaced with risk.factors
priority.score	Present	Replaced with risk.score
risk	Not present	Newly introduced - replaces priority
risk.factors	Not present	Newly introduced - replaces priority.factors
risk.factors[i].included_in_score risk.factors[i].links risk.factors[i].links.evidence risk.factors[i].links.evidence.href risk.factors[i].links.evidence.meta risk.factors[i].name risk.factors[i].updated_at risk.factors[i].value	Not present	Newly introduced
risk.score	Not present	Newly introduced replaces priority.score
risk.score.model risk.score.updated_at risk.score.value	Not present
problems	Present	No change
resolution	Only for cloud issues	For all issue types
severities	Present - Not populated	Removed as not populated and will not be
status	Present	No change
title	Present	No change
tool	Present	No change
type	Present	No change
updated_at	Present	No change
id	URI format (consists of key & scan_item.id)	UUID format
relationships.ignore	Present	No change
relationships.organization	Present	No change
relationships.policies	Present - Not populated	Removed as not populated and will not be
relationships.previous	Present - Not populated	Removed as not populated and will not be
relationships.scan_item	Present	No change
relationships.test_execution	Present	No change

Comparison of filters in experimental vs GA API

Filter by	Purpose	Experimental	GA
starting_after	return the page of results immediately after this cursor	Present	No change
ending_before	return the page of results immediately before this cursor	Present	No change
limit	number of results to return per page	Present	No change
scan_item.id	filter issues through their scan item relationship	Present	No change
scan_item.type	filter issues through their scan item relationship	Present	No change
type	filter by issue type	Present	No change
updated_after	filter issues updated after this date	Present	No change
updated_before	filter issues updated before this date	Not present	Newly introduced
created_before	filter issues created before this date	Not present	Newly introduced
created_after	filter issues created after this date	Not present	Newly introduced
effective_severity_level	filter issues by one or more effective severity levels	Not present	Newly introduced
status	filter by an issues status	Not present	Newly introduced
ignored	filter issues by their ignored status	Not present	Newly introduced