---
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}` 已**弃用**。
其上的每个响应都携带：

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

`Link` 给出替代你所调用 URL 的确切地址。停用日期已过：这些路径随时可能停止响应，请迁移到 `/v1`。

## v1 中重命名的接口

有三个 AliExpress 接口属于该平台自己的旧式命名。它们**没有 `v1` URL**：在 `/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` 会改变响应，
> 因此请同时迁移解析代码。

其他所有路径只需加上前缀：`/walmart/search` 变为 `/v1/walmart/search`，请求和响应都没有任何变化。