---
title: "요청 및 응답"
slug: "api-call-std-requestresponse"
updated: 2026-10-22T10:46:03Z
published: 2026-10-22T10:46:03Z
canonical: "api-gov.ncloud-docs.com/api-call-std-requestresponse"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api-gov.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 요청 및 응답

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)부터의 경과 시간 (밀리초) - API Gateway 서버와 5분 이상 시간차 발생 시 유효하지 않은 요청으로 간주 |
| `x-ncp-iam-access-key` | Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key - Access Key 발급 및 확인: [인증키 생성](/docs/api-call-std-auth) 참조 - 서브 계정의 Access Key 발급 및 확인: [서브 계정 생성](https://guide-gov.ncloud-docs.com/docs/subaccount-use#%EC%84%9C%EB%B8%8C-%EA%B3%84%EC%A0%95-%EC%83%9D%EC%84%B1) 참조 |
| `x-ncp-apigw-signature-v2` | Required | 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명 - Secret Key 발급 및 확인: [인증키 생성](/docs/api-call-std-auth) 참조 - 서명 생성: [시그니처 생성](/docs/api-call-std-auth) 참조 |

주의

- `x-ncp-apigw-timestamp` 값은 시그니처 생성 시 입력한 timestamp 값과 반드시 동일한 값이어야 합니다.
- 인증 헤더 외 요청 헤더는 다음 규칙에 따라 구성되어 있습니다.
  - 공통 헤더: `x-ncp-` 형식
  - 서비스 고유 헤더: `x-ncp-{서비스 식별자}-` 형식

### 요청 쿼리 파라미터

응답 결과의 페이지네이션, 정렬, 필터링을 위한 공통 요청 쿼리 파라미터를 제공합니다. 실제 적용 방식은 서비스별 API 가이드에서 확인해 주십시오.

#### 페이지네이션

API별 특성에 따라 두 가지 방식의 페이지네이션을 제공합니다.

- 커서 기반(`pageSize`, `nextToken`): 데이터의 양이 많거나 조회 중 데이터가 지속적으로 변경될 수 있는 경우
- 오프셋 기반(`pageNo`, `pageSize`): 오프셋 기반 페이지네이션은 전체 항목 수를 확인하거나 특정 페이지로 이동해야 하는 경우

각 방식별 요청 쿼리 파라미터에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `pageSize` | Integer | Optional | 페이지당 조회할 항목 수 - 기본값: `20` - 최대 값과 기본값은 서비스별로 상이할 수 있음 |
| `nextToken` | String | Optional | 다음 페이지를 조회할 때 사용하는 토큰 (커서 기반 페이지네이션) - 최초 요청에는 지정하지 않음 - 이전 요청의 응답에 포함된 `nextToken` 값을 입력 - 응답의 `nextToken` 값이 `null`이면 마지막 페이지 |
| `pageNo` | Integer | Optional | 조회할 페이지 번호 (오프셋 기반 페이지네이션) - 0~N (기본값: `0`) - 첫 번째 페이지: `pageNo=0` - 두 번째 페이지: `pageNo=1` |

#### 정렬

정렬 관련 요청 쿼리 파라미터에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `sort` | String | Optional | 정렬 기준 필드와 정렬 방향 - `asc` \| `desc` - `asc`: 오름차순 (기본값) - `desc`: 내림차순 - `,`로 구분해 입력 - <예시> `sort=createdDateTime,desc` |

#### 필터링

특정 값을 만족하는 경우만 필터링하여 반환하거나, 범위 조건이나 부정 조건과 같이 복합적인 조건을 만족하는 경우만 필터링하여 반환하려는 경우에 사용할 수 있는 요청 쿼리 파라미터에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `{필드명}` | - | Optional | 값의 일치 여부를 확인하는 단순 필터 조건 - 조건을 적용할 필드명을 쿼리 파라미터로 지정 - 필터 대상 필드는 서비스별 API 가이드 참조 - <예시> `status=RUNNING` |
| `filter` | String | Optional | 범위 조건이나 부정 조건 등 복합 조건을 지정하는 조건식 - 비교 연산자: `=`, `!=`, `&lt;`, `&lt;=`, `&gt;`, `&gt;=` - 논리 연산자: `AND`, `OR`, `NOT` - 하위 항목에 조건 지정 시 `.`으로 구분 - `filter`를 지원하는 API에서만 사용 가능하며, 필터 대상과 조건은 서비스별 API 가이드 참조 |

### 요청 예시

요청 예시는 다음과 같습니다.

```
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 가이드를 참조해 주십시오. 단, 제공 중인 [공통 요청 쿼리 파라미터](/docs/api-call-std-requestresponse#%EC%9A%94%EC%B2%AD%EC%BF%BC%EB%A6%AC%ED%8C%8C%EB%9D%BC%EB%AF%B8%ED%84%B0)를 사용하여 호출한 경우, 다음과 같은 필드가 응답 바디에 포함되어 반환됩니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `pageSize` | Integer | - | 페이지당 항목 수 |
| `nextToken` | String | - | 다음 페이지를 조회할 때 사용하는 토큰 (커서 기반 페이지네이션) - 마지막 페이지이면 `null` |
| `totalElements` | Integer | - | 조건에 부합하는 전체 항목 수 (오프셋 기반 페이지네이션) |
| `totalPages` | Integer | - | 조건에 부합하는 전체 페이지 수 (오프셋 기반 페이지네이션) |
| `pageNo` | Integer | - | 현재 페이지 번호 (오프셋 기반 페이지네이션) |

참고

공통 오류 응답 바디는 [오류 처리](/docs/api-call-std-errorhandling)에서 확인해 주십시오.

### 응답 상태 코드

Standardized API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [오류 처리](/docs/api-call-std-errorhandling)를 참조해 주십시오.

참고

리소스 생성이나 대량 데이터 처리처럼 처리 시간이 긴 작업은 요청 즉시 `202 Accepted`로 응답합니다. 이후 작업의 처리 상태를 조회하여 진행 상황과 결과를 확인할 수 있습니다. 작업의 처리 상태를 조회하는 방법은 각 서비스의 API 가이드를 참조해 주십시오.

### 응답 예시

응답 예시는 다음과 같습니다.

- `Content-type: application/json`

```
HTTP/1.1 200 OK
{
  "id": "user-001",
  "name": "User 1",
  "email": "user1@example.com"
}
```
- `Content-type: application/xml`

```
HTTP/1.1 200 OK
<user>
    <id>user-001</id>
    <name>User 1</name>
    <email>user1@example.com</email>
</user>
```