VPC 환경에서 이용 가능합니다.
Ncloud API 표준 규격을 적용한 API입니다.
Standardized API에서 공통으로 사용하는 요청 형식과 응답 형식을 설명합니다.
일부 서비스의 API는 요청 형식과 응답 형식이 상이할 수 있습니다. 서비스별 API 가이드에서 확인해 주십시오.
요청
공통 요청 형식을 설명합니다.
요청 형식
API URL은 서비스별 API 가이드에서 확인해 주십시오.
리소스 경로
리소스에 수행하는 작업에 따라 HTTP 메서드를 구분하여 다음과 같이 사용합니다.
| 메서드 | 동작 | 메서드 및 리소스 경로 예시 |
|---|---|---|
GET |
목록 조회 | GET /users |
| 단건 조회 | GET /users/{userId} |
|
일괄 조회
|
GET /users/batch-get |
|
POST |
생성 | POST /users |
| 일괄 생성, 일괄 수정, 일괄 삭제 | POST /users/batch-create, POST /users/batch-update, POST /users/batch-delete |
|
커스텀 작업
|
POST /login, POST /servers/{serverId}/reboot, POST /operations/{operationId}/cancel |
|
PUT |
전체 수정 | PUT /users/{userId} |
PATCH |
일부 수정 | PATCH /users/{userId} |
DELETE |
삭제 | DELETE /users/{userId} |
PUT은 리소스의 전체 정보를 변경할 때 사용하고, PATCH는 리소스의 일부 정보만 변경할 때 사용합니다. 단, PUT 요청 시 요청에 포함하지 않은 항목의 처리 방식은 서비스에 따라 상이할 수 있습니다.
요청 헤더
요청 헤더에 대한 설명은 다음과 같습니다.
| 필드 | 필수 여부 | 설명 |
|---|---|---|
x-ncp-apigw-timestamp |
Required | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간 (밀리초)
|
x-ncp-iam-access-key |
Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key |
x-ncp-apigw-signature-v2 |
Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명 |
x-ncp-apigw-timestamp값은 시그니처 생성 시 입력한 timestamp 값과 반드시 동일한 값이어야 합니다.- 인증 헤더 외 요청 헤더는 다음 규칙에 따라 구성되어 있습니다.
- 공통 헤더:
x-ncp-형식 - 서비스 고유 헤더:
x-ncp-{서비스 식별자}-형식
- 공통 헤더:
요청 쿼리 파라미터
응답 결과의 페이지네이션, 정렬, 필터링을 위한 공통 요청 쿼리 파라미터를 제공합니다. 실제 적용 방식은 서비스별 API 가이드에서 확인해 주십시오.
페이지네이션
API별 특성에 따라 두 가지 방식의 페이지네이션을 제공합니다.
- 커서 기반(
pageSize,nextToken): 데이터의 양이 많거나 조회 중 데이터가 지속적으로 변경될 수 있는 경우 - 오프셋 기반(
pageNo,pageSize): 오프셋 기반 페이지네이션은 전체 항목 수를 확인하거나 특정 페이지로 이동해야 하는 경우
각 방식별 요청 쿼리 파라미터에 대한 설명은 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
pageSize |
Integer | Optional | 페이지당 조회할 항목 수
|
nextToken |
String | Optional | 다음 페이지를 조회할 때 사용하는 토큰 (커서 기반 페이지네이션)
|
pageNo |
Integer | Optional | 조회할 페이지 번호 (오프셋 기반 페이지네이션)
|
정렬
정렬 관련 요청 쿼리 파라미터에 대한 설명은 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
sort |
String | Optional | 정렬 기준 필드와 정렬 방향
|
필터링
특정 값을 만족하는 경우만 필터링하여 반환하거나, 범위 조건이나 부정 조건과 같이 복합적인 조건을 만족하는 경우만 필터링하여 반환하려는 경우에 사용할 수 있는 요청 쿼리 파라미터에 대한 설명은 다음과 같습니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
{필드명} |
- | Optional | 값의 일치 여부를 확인하는 단순 필터 조건
|
filter |
String | Optional | 범위 조건이나 부정 조건 등 복합 조건을 지정하는 조건식
|
요청 예시
요청 예시는 다음과 같습니다.
curl --location --request GET 'https://example.gov-apigw.ntruss.com/users?pageSize=20&sort=createdDateTime,desc' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json'
응답
공통 응답 형식을 설명합니다.
응답 바디
응답 바디는 서비스 또는 API에 따라 상이하므로 서비스별 API 가이드를 참조해 주십시오. 단, 제공 중인 공통 요청 쿼리 파라미터를 사용하여 호출한 경우, 다음과 같은 필드가 응답 바디에 포함되어 반환됩니다.
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
pageSize |
Integer | - | 페이지당 항목 수 |
nextToken |
String | - | 다음 페이지를 조회할 때 사용하는 토큰 (커서 기반 페이지네이션)
|
totalElements |
Integer | - | 조건에 부합하는 전체 항목 수 (오프셋 기반 페이지네이션) |
totalPages |
Integer | - | 조건에 부합하는 전체 페이지 수 (오프셋 기반 페이지네이션) |
pageNo |
Integer | - | 현재 페이지 번호 (오프셋 기반 페이지네이션) |
공통 오류 응답 바디는 오류 처리에서 확인해 주십시오.
응답 상태 코드
Standardized API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 오류 처리를 참조해 주십시오.
리소스 생성이나 대량 데이터 처리처럼 처리 시간이 긴 작업은 요청 즉시 202 Accepted로 응답합니다. 이후 작업의 처리 상태를 조회하여 진행 상황과 결과를 확인할 수 있습니다. 작업의 처리 상태를 조회하는 방법은 각 서비스의 API 가이드를 참조해 주십시오.
응답 예시
응답 예시는 다음과 같습니다.
Content-type: application/jsonHTTP/1.1 200 OK { "id": "user-001", "name": "User 1", "email": "user1@example.com" }Content-type: application/xmlHTTP/1.1 200 OK <user> <id>user-001</id> <name>User 1</name> <email>user1@example.com</email> </user>