REST API 소개
Snyk REST API는 JSON:API 표준을 기반으로 하며, OpenAPI 3.0.3에서 정의되었습니다. API 개발에 대한 진화적 접근을 나타내며 각 엔드포인트는 버전별로 구성되어 있습니다. 자세한 정보는 이 페이지의 버전 관리 섹션을 참조하십시오.
API URL
Snyk은 다음 지역에 호스팅됩니다. 각 지역은 고유한 기본 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
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": "클라이언트 요청이 OpenAPI 사양에 부합하지 않았습니다.",
...
}
]
}버전 관리
Snyk REST API는 각 엔드포인트 버전 계약을 가지고 있습니다. GA 버전 간의 차이에 대한 정보는 API 변경 로그를 참조하십시오. 각 엔드포인트는 자체 릴리스 및 지원 주기를 갖으며, 다른 Snyk REST API의 엔드포인트와는 독립적입니다. 가장 명시적인 형태에서, 엔드포인트 버전 번호는 날짜와 안정성 트리를 포함합니다. 예를 들어:
2023-11-27~beta이 버전 번호는 요청된 엔드포인트가 2023-11-27 또는 이전 beta의 안정성 수준을 갖는다는 것을 나타냅니다. 가능한 안정성 수준은 다음과 같습니다:
ga- 일반적으로 이용 가능 (기본값). 다음 GA 릴리스 이후 적어도 6개월 동안 Snyk이 지원합니다.beta- 다음 베타 또는 GA 릴리스 이후 적어도 3개월 동안 Snyk이 지원합니다.experimental- 실험적 엔드포인트는 불안정하며 기술 미리보기로 간주해야 합니다. 실험 버전은 중단될 수 있으며 변화를 가져올 수 있습니다.
기본적인 경우에는 일반적으로 이용 가능한 경우 버전 번호 자체에 특정 안정성 수준이 명시되지 않습니다. 즉, 날짜만 존재합니다. 예를 들어:
2023-11-27이는 요청된 엔드포인트가 2023-11-27 이거나 이전의 일반적으로 이용 가능한 안정성 트리에 속한다는 것을 의미합니다.
요청된 엔드포인트가 특정 안정성 수준에 있는 경우, Snyk은 최신 버전을 제공합니다. 요청된 엔드포인트가 2023-09-29에 베타 버전을 가지고 있고 2024-01-23에 GA 버전을 가지고 있으며 요청된 엔드포인트가 2024-01-23~beta 이후인 경우에는 Snyk은 GA 버전으로 해석합니다.
세분화된 버전 컨트롤을 통해 Snyk은 혁신적인 개선을 도입할 수 있습니다. 이는 작은 또는 미세한 하위 호환되지 않는 변경이 필요할 수 있습니다. 그러나 세분화된 버전 컨트롤을 사용함으로써, Snyk은 기존 엔드포인트를 지원하기 위한 보장된 기간 동안 보다 빠르게 혁신적인 개선을 도입할 수 있습니다.
엔드포인트가 폐기되면 해당 엔드포인트 계약이 더 이상 지원되지 않는 날짜를 나타내는 Sunset 헤더가 포함됩니다. 예를 들어:
Sunset: "2021-11-11"페이지네이션
Snyk REST API의 모든 엔드포인트는 커서 기반 페이지네이션을 사용합니다. 이 형태의 페이지네이션은 컬렉션이 반복되는 동안 수정될 때 일관되지 않은 결과를 방지하는 데 도움이 됩니다. 그러나 커서 기반 페이지네이션은 일관되지 않은 결과를 완전히 방지하지는 않으며, 요청 후에 요청된 정렬 순서에 따라 이전 페이지에 삽입된 항목과 같이 일관하지 않은 결과가 발생할 수 있습니다.
불일치한 결과의 가능성을 완화하기 위해 Snyk은 기본적으로 삽입 순서로 정렬하여 정렬합니다. 따라서 이전 페이지에 항목이 삽입되는 등의 상황이 발생하지 않습니다. 그러나 sort 매개변수를 지정하면 일관된 페이지네이션이 보장되지 않습니다. 일관된 페이지네이션이 중요한 경우 불일치한 결과가 발생할 경우 새 요청을 제출할 수 있습니다. 작업 흐름에 중요한 일관된 페이지네이션이라면 기본 삽입 순서를 사용하십시오.
API 응답을 받을 때마다 응답 본문에 다음과 같은 적절한 링크가 포함됩니다:
{
"data": [ ... ],
"links": {
"prev": "/orgs/123-abc-def-456/projects?version=2024-06-10&ending_before=v1.eyJpZCI6Mz1zODQyMH0%3D"
"next": "/orgs/123-abc-def-456/projects?version=2024-06-10&starting_after=v1.eyJpZCI6Mz1zODQyMH0%3D"
}
}이 링크에는 페이지네이션을 쉽게 만들기 위한 미리 정의된 매개변수들이 포함되어 있습니다. 이러한 매개변수는 다음과 같습니다:
starting_after: Snyk 내부 블롭으로, 본인이 본 마지막 기록 및 이것 이후의 기록을 원하는 것을 Snyk에 알리는 것ending_before: Snyk 내부 블롭으로, 본인이 본 첫 번째 기록 및 이것 이전의 기록을 원하는 것을 Snyk에 알리는 것limit: 한 페이지 당 레코드 수
오류
오류는 JSON:API 명세를 준수하며, 다음과 같이 원인을 나타내기 위한 경로 기반 정보를 포함합니다:
{
"errors": [
{
"id": "0418e907-a89e-4736-9a5b-91a2022e0899",
"detail": "알 수 없는 쿼리 매개변수 'unknown'",
"status": "400",
"source": {
"parameter": "unknown"
}
}
]
}비율 제한
API 키 당 분당 1620개의 요청 제한이 있습니다. 제한을 초과하는 모든 요청은 요청이 멈출 때까지 (한 분간) 레이트 제한 간격 동안 429 상태 코드와 함께 응답을 받게 됩니다.
시스템 전반적인 건강을 유지하기 위해 때때로 Snyk은 새로운 비율 제한을 도입할 수 있습니다. 이는 파괴적인 변경으로 간주되지 않습니다. 모든 클라이언트는 429 응답을 올바르게 처리하고 해당 요청을 나중에 안전하게 다시 시도할 수 있습니다.
Last updated