---
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` 下调用
会返回 `404 NOT_IN_V1`，并附带指向后继地址的 `Link` 头：

| 已弃用 | 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`，请求和响应完全不变。