---
title: "버전 관리"
description: "버전은 경로에 있습니다. 현재 버전은 v1입니다. v1에 추가될 수 있는 것과, 버전 없는 이전 URL의 동작을 설명합니다."
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt)

## 버전은 경로에 있습니다

모든 엔드포인트는 버전 구간 아래에 있습니다. **`v1`이 현재 버전**이며, 이 버전을 사용하세요.

```bash
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" \
  -H "x-api-key: $APINOA_API_KEY"
```

모든 응답은 응답한 버전을 `x-api-version` 헤더에 담습니다.

## v1 안에서 바뀔 수 있는 것

- **추가는 합니다.** 새 응답 필드, 새 선택 파라미터, 새 플랫폼, 새 오퍼레이션은 버전을 올리지 않고 `v1`에
  추가됩니다. 응답은 관대하게 파싱하고, 모르는 것은 무시하세요.
- **깨뜨리지는 않습니다.** 필드를 없애거나 이름을 바꾸거나, 타입이나 단위를 바꾸거나, 선택
  파라미터를 필수로 만드는 일은 자체 경로 구간을 가진 **새 버전**이 되며, `v1`을 고치는 일은 없습니다.

필드가 없다는 것은 처음부터 "플랫폼이 밝히지 않았다"는 뜻이었고, 지금도 그렇습니다. 변경이 아닙니다.

## 버전 없는 URL

버전이 없는 이전 형식 `https://gateway.apinoa.com/{platform}/{operation}`은 **지원 중단(deprecated)**되었습니다.
이 경로의 모든 응답에는 다음 헤더가 붙습니다.

| 헤더 | 값 |
|---|---|
| `Deprecation` | `true` |
| `Sunset` | `Tue, 20 Oct 2026 00:00:00 GMT` |
| `Link` | `<https://gateway.apinoa.com/v1/…>; rel="successor-version"` |

`Link`는 호출한 URL을 대체하는 정확한 URL을 알려 줍니다. 종료일이 이미 지났으므로 이 경로는
언제든 응답을 멈출 수 있습니다. `/v1`로 옮기세요.

## v1에서 이름이 바뀐 것

AliExpress 엔드포인트 세 개는 이 마켓플레이스의 이전 방식에 속합니다. 이들에는 **`v1` URL이 없습니다**.
`/v1` 아래에서는 후속 경로를 가리키는 `Link`와 함께 `404 NOT_IN_V1`로 응답합니다.

| 지원 중단 | v1 |
|---|---|
| `/aliexpress/keyword-search` | [`/v1/aliexpress/search`](/docs/api-reference/aliexpress/search) |
| `/aliexpress/product-details` | [`/v1/aliexpress/product`](/docs/api-reference/aliexpress/product) |
| `/aliexpress/visual-search`, `/aliexpress/image-search` | [`/v1/aliexpress/image-search`](/docs/api-reference/aliexpress/image-search) |

> **Warning:** **`image-search`는 응답 형태가 바뀝니다.** 버전 없는 `/aliexpress/image-search`는 AliExpress 고유의 이전
> 형태를 돌려주고, `/v1/aliexpress/image-search`는 모든 마켓플레이스가 돌려주는 공통 `SearchResult`를 돌려줍니다. 이
> URL을 `/v1`로 옮기면 응답이 바뀌므로, 파싱 코드도 함께 옮기세요.

다른 모든 경로는 접두사만 붙이면 됩니다. `/walmart/search`는 `/v1/walmart/search`가 되며, 요청이나
응답은 전혀 바뀌지 않습니다.