> ## Documentation Index
> Fetch the complete documentation index at: https://duxweb-22.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 基础介绍

> DuxCMS 采用 restful api 风格的接口路由，并且每次请求都需要进行接口签名认证，以提高安全性，使用 api 可以将前端应用轻松接入到本系统中。

<Note>
  推荐在使用签名的同时使用 ssl 进行接口数据传输，已达到更好的安全性需求。
</Note>

## 请求说明

### 基础 url

基础请求的 url 为 `/api/` 开头的路径。

```
http://example.text/api/
```

### 数据格式

您可以使用 xml、json 等格式进行请求，请求的内容请使用请求头 `Content-Type` 设置，请求的结果请使用 `Accept` 来获得期望数据格式，未设置则返回 html 格式，如虾：

```
HEADERS

Content-Type: application/json
Accept: application/json
```

## 签名说明

DuxCMS Api 签名使用 http headers 传输签名后的参数。

### 签名内容

内容格式如下：

```
请求路径\n
params1=a&params2=b\n
10位时间戳
```

1. 请求路径，不包含域名，如 /content/article
2. 请求参数，如果不存在请留空，否则为 url 转义前参数
3. 时间戳，unix 10 位时间戳

签名内容使用 "\n" 换行符进行拼接。

### 签名字符串

```
HMAC_256("签名内容", "Api密钥")
```

Api 密钥请在后台的接口管理中添加获取，请根据对应语言针对签名内容进行"HMAC 256加密"生成签名字符串。

### 请求结构体

请讲签名后的字符串带入到请求头中，示例如下：

```
GET:
https://example.test/content/article?params1=a&params2=b

HEADERS:
Content-Date: 10位时间戳
Content-MD5: 签名字符串
AccessKey: Api ID

BODY:
...

```

1. Content-Date 与签名时使用的时间戳须一致。
2. Content-MD5 通过 "HMAC 256" 加密后的签名字符串。
3. AccessKey 后台接口管理中添加获取的Api ID。

### 签名成功

签名成功后将会收到正确的返回数据，如果签名失败则会收到 402 或者 408 状态码。

## 请求成功

请求成功后将会收到 http 状态码为 200，同时返回以下 json 结构。

```json theme={null}
{
  "code": 200,
  "message": "ok",
  "data": {},
  "meta": {}
}
```

1. code 状态码与 http 状态码保持一致，
2. message 成功消息
3. data 成功后的主体数据，根据请求的结果为对象或者数据。
4. meta 元数据，一般为非主体数据，如分页信息、附加数据等。

## 请求失败

请求失败后将会收到 http 状态码为非 200，同时返回以下 json 结构，如果没有以下结构则需要首先处理 http 中的请求异常信息。

```json theme={null}
{
  "code": 500,
  "message": "文章不存在"
}
```

1. code 状态码与 http 状态码保持一致，
2. message 失败提示消息。