Cafe Guide API 使用文档

Base URL https://cafe-guide-api.pages.dev

Content-Type application/json

数据对象 咖啡馆记录 item

数据字段

id string，唯一标识，例如 morning-mist
name string，店名，新增时必填
city string，城市，新增时必填
district string，街区
location string，展示地点，例如 上海 · 武康路
types string[]，咖啡类型，例如 ["手冲", "浅烘"]
score number，评分，范围 0-100
tags string[]，标签
drink string，推荐饮品
flavor string，风味描述
bestFor string，适合人群
advice string，选择建议

端点

GET /api/items

获取咖啡馆列表。支持按城市、咖啡类型和关键词筛选。

查询参数：city、type、q

请求示例

curl "https://cafe-guide-api.pages.dev/api/items?city=上海&type=手冲"

响应格式

{
  "count": 1,
  "items": [
    {
      "id": "morning-mist",
      "name": "晨雾咖啡",
      "city": "上海",
      "types": ["手冲", "浅烘"],
      "score": 92
    }
  ]
}

GET /api/items/:id

通过 ID 获取单条咖啡馆记录。

请求示例

curl https://cafe-guide-api.pages.dev/api/items/morning-mist

响应格式

{
  "item": {
    "id": "morning-mist",
    "name": "晨雾咖啡",
    "city": "上海",
    "district": "武康路",
    "location": "上海 · 武康路"
  }
}

POST /api/items

新增一条咖啡馆记录。请求体必须是 JSON，至少包含 name 和 city。

请求示例

curl -X POST https://cafe-guide-api.pages.dev/api/items \
  -H "Content-Type: application/json" \
  -d '{
    "name": "新咖啡馆",
    "city": "上海",
    "district": "静安寺",
    "types": ["手冲"],
    "score": 88
  }'

响应格式

{
  "item": {
    "id": "cafe-mrdod7rw-507ems",
    "name": "新咖啡馆",
    "city": "上海",
    "district": "静安寺",
    "location": "上海 · 静安寺",
    "types": ["手冲"],
    "score": 88
  }
}

PUT /api/items/:id

更新一条已有记录。只需要传入要修改的字段。

请求示例

curl -X PUT https://cafe-guide-api.pages.dev/api/items/morning-mist \
  -H "Content-Type: application/json" \
  -d '{"score": 94, "tags": ["手冲吧台", "安静", "推荐"]}'

响应格式

{
  "item": {
    "id": "morning-mist",
    "score": 94,
    "tags": ["手冲吧台", "安静", "推荐"]
  }
}

DELETE /api/items/:id

删除一条已有记录。

请求示例

curl -X DELETE https://cafe-guide-api.pages.dev/api/items/api-test-cafe

响应格式

{
  "ok": true,
  "id": "api-test-cafe"
}

错误响应

{
  "error": "未找到该记录"
}

常见状态码：400 请求格式错误，404 记录不存在。

机器可读文档

OpenAPI JSON 文档：/openapi.json