버전 관리
버전은 경로에 있습니다. 현재 버전은 v1이며, 버전 없는 URL도 계속 동작합니다. 버전을 올리지 않고 바뀌는 것과 그렇지 않은 것.
버전은 경로에 있습니다
gateway.apinoa.com의 모든 데이터 엔드포인트는 버전 세그먼트 아래에 있습니다. 현재 버전은 v1이며,
새로 연동한다면 이 버전을 쓰면 됩니다:
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 |
/aliexpress/product-details | /v1/aliexpress/product |
/aliexpress/visual-search와 /aliexpress/image-search | /v1/aliexpress/image-search |
image-search는 두 번 확인하세요. 경로 세그먼트는 양쪽이 같지만 응답 본문은 다릅니다. 버전 없는
/aliexpress/image-search는 AliExpress 자체의 구형식을 돌려주고, /v1/aliexpress/image-search는 다른 모든
마켓플레이스와 동일한 정규화된 SearchResult를 돌려줍니다. 이 URL에 /v1을 붙이면 응답이 바뀌므로 파싱
코드도 함께 옮겨야 합니다.
/aliexpress/visual-search는 애초에 정규화된 이미지 검색이 차선책 이름을 쓴 것뿐이었습니다. 구형식이
image-search를 이미 쓰고 있었기 때문입니다. v1 안에는 구형식이 없으므로 표준 이름을 쓸 수 있게 되었고,
경로 예외도 사라졌습니다.
나머지는 모두 접두사만 붙이면 됩니다. /walmart/search는 /v1/walmart/search가 되고, 요청과 응답은 전혀
달라지지 않습니다.