REST API 정보
Snyk REST API는 JSON:API 표준 및 OpenAPI 3.0.3을 기반으로 하며, 각 엔드포인트에 버전이 지정된 진화된 API 개발 방식을 채택하고 있습니다. 자세한 내용은 이 페이지의 버전 관리(Versioning) 섹션을 참조하십시오.
API URL
Snyk은 다음 지역(Region)에서 호스팅됩니다. 각 지역에는 고유한 기본 URL(Base URL)이 있습니다. API를 호출할 때는 해당 지역의 URL을 사용하십시오.
SNYK-US-01
https://api.snyk.io/rest
SNYK-US-02
https://api.us.snyk.io/rest
SNYK-EU-01
https://api.eu.snyk.io/rest
SNYK-AU-01
https://api.au.snyk.io/rest
이 API는 HTTPS를 통해서만 사용할 수 있습니다. HTTP를 통해 API를 호출하면 모든 요청에 대해 404 응답이 반환됩니다.
JSON:API Content-Type 헤더
Snyk REST API는 몇 가지 주의 사항을 제외하고는 대체로 JSON:API 표준을 준수합니다. JSON:API는 클라이언트가 리소스를 요청 및 수정하는 방법과 서버가 요청에 응답하는 방법에 대한 명확한 사양을 정의합니다.
REST API를 사용할 때 데이터를 포함하는 모든 요청은 다음 헤더와 함께 보내십시오.
Content-Type: application/vnd.api+json그렇지 않으면 400 "Bad Request" 응답이 반환됩니다.
HTTP/1.1 400 Bad Request
{
"errors": [
{
"status": "400",
"detail": "Client request did not conform to OpenAPI specification",
...
}
]
}버전 관리
2024-10-15 이후 버전 사용
API 참조 예시에는 ?version=text가 플레이스홀더로 포함되어 있으며, 여기서 text는 필수 날짜 형식의 버전 문자열을 나타냅니다. Snyk은 특정 이유로 이전 버전을 사용해야 하는 경우가 아니라면 버전 번호로 2024-10-15를 사용할 것을 권장합니다. 현재 날짜를 사용할 수도 있으며, 이 경우 API의 가장 최신 버전이 호출됩니다. 날짜 형식은 YYYY-MM-DD입니다.
2024-10-15 이전 버전 사용
다음 정보는 2024-10-15 이전 버전을 호출하는 경우에 적용됩니다. Snyk REST API는 엔드포인트별 버전 계약을 가집니다. 정식 버전(GA) 간의 차이점에 대한 정보는 API 변경 로그(API Changelog)를 참조하십시오. 각 엔드포인트는 Snyk REST API 내의 다른 엔드포인트와 독립적으로 고유한 릴리스 및 지원 수명 주기를 가질 수 있습니다. 가장 명시적인 형태의 엔드포인트 버전 번호에는 날짜와 안정성 트리(stability tree)가 포함됩니다. 예:
이 버전 번호는 요청된 엔드포인트가 안정성 수준 2023-11-27 또는 그 이전의 beta임을 나타냅니다. 가능한 안정성 수준은 다음과 같습니다.
ga- 정식 버전(Generally Available), 기본값입니다. Snyk은 다음 GA 릴리스 이후 최소 6개월 동안 이를 지원합니다.beta- 베타(Beta). Snyk은 다음 베타 또는 GA 릴리스 이후 최소 3개월 동안 이를 지원합니다.experimental- 실험적(Experimental). 실험적 엔드포인트는 불안정한 것으로 간주되며 기술 미리 보기로 간주됩니다. 실험적 버전은 중단되는 변경(Breaking changes)을 도입할 수 있으며 언제든지 중단될 수 있습니다.
정식 버전(GA)의 경우, 버전 번호 자체에 안정성 수준이 명시되지 않습니다. 즉, 날짜만 표시됩니다. 예:
이는 요청된 엔드포인트가 정식 버전 안정성 트리에서 2023-11-27 또는 그 이전 버전이어야 함을 의미합니다.
요청된 엔드포인트가 특정 안정성 수준에 있는 경우, Snyk은 요청된 날짜 또는 그 이전에 릴리스된 최신 버전(해당 안정성 또는 그 이상)을 제공합니다. 예를 들어, 요청된 엔드포인트의 베타 버전이 2023-09-29에 있고 GA 버전이 2024-01-23에 있는 경우, 요청된 엔드포인트가 2024-01-23~beta 이후라면 Snyk은 GA 버전으로 연결합니다.
세분화된 버전 제어를 통해 Snyk은 점진적인 향상된 기능을 도입할 수 있습니다. 여기에는 사소한 하위 호환성 위배 변경이 필요할 수 있습니다. 그러나 세분화된 버전 제어를 사용하면 보장된 기간 동안 기존 엔드포인트를 지원하면서 더 빠르게 개선된 기능을 제공할 수 있습니다.
엔드포인트가 지원 종료(Deprecated)로 표시된 후에는 해당 엔드포인트 계약이 더 이상 지원되지 않는 날짜를 나타내는 Sunset 헤더가 포함됩니다. 예:
페이지네이션
Snyk REST API의 모든 엔드포인트는 커서 기반(cursor-based) 페이지네이션을 사용하여 페이지가 매겨집니다. 이 방식은 컬렉션이 반복되는 동안 수정될 때 발생할 수 있는 일관되지 않은 결과를 방지하는 데 도움이 됩니다. 그러나 커서 기반 페이지네이션이 일관되지 않은 결과를 완전히 방지하지는 못합니다. 예를 들어, 요청이 이루어진 후 요청된 정렬 순서에 따라 이전 페이지에 항목이 삽입되는 경우 발생할 수 있습니다.
일관되지 않은 결과가 발생할 가능성을 완화하기 위해 Snyk은 기본적으로 삽입 순서로 정렬하므로 이전 페이지에 항목이 삽입될 수 없습니다. 그러나 sort 매개변수를 지정하면 더 이상 일관된 페이지네이션이 보장되지 않습니다. 일관되지 않은 결과가 보이면 새 요청을 제출할 수 있습니다. 워크플로우에서 일관된 페이지네이션이 중요한 경우 기본 삽입 정렬 순서를 사용하십시오.
API 응답을 받을 때마다 응답 본문에 다음과 같이 적절한 링크가 포함됩니다.
이러한 링크에는 페이지네이션을 쉽게 만들기 위해 사전 정의된 매개변수가 포함되어 있습니다. 이러한 매개변수는 다음의 조합입니다.
starting_after: Snyk 내부적으로 사용되는 불투명한 블롭(blob)으로, Snyk에게 사용자가 마지막으로 확인한 _마지막 레코드_를 알려주고 그 _이후_의 레코드를 원한다는 것을 나타냅니다.ending_before: Snyk 내부적으로 사용되는 불투명한 블롭으로, Snyk에게 사용자가 처음으로 확인한 _첫 번째 레코드_를 알려주고 그 _이전_의 레코드를 원한다는 것을 나타냅니다.limit: 페이지당 레코드 수
오류
오류는 JSON:API 사양을 준수하며 다음과 같이 근본 원인을 나타내기 위해 경로 기반 정보를 포함합니다.
속도 제한
API 키당 분당 1,620회 요청으로 제한됩니다. 한도를 초과하는 모든 요청은 속도 제한 간격(1분) 동안 요청이 중단될 때까지 상태 코드 429 - Too many requests 응답을 받게 됩니다.
Snyk은 시스템 전체의 상태를 유지하기 위해 때때로 새로운 속도 제한을 도입할 수 있습니다. 이는 중단되는 변경으로 간주되지 않습니다. 모든 클라이언트는 429 응답을 올바르게 처리해야 하며 이러한 요청은 나중에 안전하게 재시도할 수 있습니다.
Last updated