---
title: "버전 관리"
description: "버전은 경로에 있습니다. 현재 버전은 v1이며, 버전 없는 URL도 계속 동작합니다. 버전을 올리지 않고 바뀌는 것과 그렇지 않은 것."
---

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

`gateway.apinoa.com`의 모든 데이터 엔드포인트는 버전 세그먼트 아래에 있습니다. **현재 버전은 v1**이며,
새로 연동한다면 이 버전을 쓰면 됩니다:

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

## 버전 없는 URL도 계속 동작합니다

기존 `https://gateway.apinoa.com/{marketplace}/{op}` 형식은 지금까지와 똑같은 응답 본문으로 계속 동작합니다.
제거된 것이 아니라 지원 종료 예정 상태이며, 모든 응답에 다음 헤더가 붙습니다:

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

`Link` 헤더는 방금 호출한 URL을 대체하는 정확한 주소를 알려주므로, 클라이언트가 스스로 이전 경로를 찾을 수
있습니다. **2026년 10월 20일** 이후에는 버전 없는 경로가 응답을 멈출 수 있습니다. 그 전에 옮기세요.

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

- **추가합니다.** 응답의 새 필드, 새 선택 파라미터, 새 마켓플레이스와 새 오퍼레이션은 버전을 올리지 않고
  `v1`에 추가됩니다. 모르는 필드는 무시하도록 느슨하게 파싱하세요.
- **깨뜨리지 않습니다.** 필드를 없애거나 이름·타입·단위를 바꾸거나 선택 파라미터를 필수로 만드는 일은
  자체 경로 세그먼트를 가진 **새 버전**이 되며, `v1`을 고치는 방식으로는 하지 않습니다.

필드가 없다는 것은 언제나 "마켓플레이스가 알려주지 않았다"는 뜻이었고, 지금도 그렇습니다. 변경이 아닙니다.

## v1에서 이름이 바뀐 엔드포인트

AliExpress의 세 엔드포인트는 정규화 스키마보다 먼저 만들어진 그 마켓플레이스 자체 형식에 속합니다. 이들에는
**`v1` 주소가 없으며**, `/v1` 아래에서 호출하면 후속 URL을 담은 `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`을 붙이면 응답이 바뀌므로 파싱
> 코드도 함께 옮겨야 합니다.

`/aliexpress/visual-search`는 애초에 정규화된 이미지 검색이 차선책 이름을 쓴 것뿐이었습니다. 구형식이
`image-search`를 이미 쓰고 있었기 때문입니다. `v1` 안에는 구형식이 없으므로 표준 이름을 쓸 수 있게 되었고,
경로 예외도 사라졌습니다.

나머지는 모두 접두사만 붙이면 됩니다. `/walmart/search`는 `/v1/walmart/search`가 되고, 요청과 응답은 전혀
달라지지 않습니다.