name: bmob-database-restful description: "Use when interacting with Bmob backend cloud over plain HTTP / curl from ANY language that lacks a Bmob SDK — Python (requests/httpx), Go (net/http), PHP (Guzzle), C# (HttpClient), Rust (reqwest), Ruby, Java backend, Bash, Deno, server-side scripting, data migration. Also use when the user explicitly wants curl or the raw REST API URL pattern. API base domain: https://api.codenow.cn (e.g. /1/classes/Token). Triggers: /1/classes/, /1/users, /1/batch, /1/cloudQuery, /1/timestamp, /1/requestSmsCode, X-Bmob-Application-Id, X-Bmob-REST-API-Key, X-Bmob-Safe-Sign, simple auth, encrypted auth, MD5 signature, curl bmob, Bmob REST API, Bmob HTTP. NOT for JavaScript / Node / Web / Mini Program (use bmob-database-javascript), Android (use bmob-database-android), or iOS (use bmob-database-ios). If Bmob MCP is configured, generate_code MCP tool can emit ready-to-use curl for 13 operation types — prefer it over hand-writing curl." metadata: author: bmob version: "0.1.0" docs: "https://github.com/bmob/BmobDocs/blob/master/mds/data/restful/develop_doc.md" docs_raw: "https://raw.githubusercontent.com/bmob/BmobDocs/master/mds/data/restful/develop_doc.md"

Bmob Database — REST API

Bmob REST API 是 跨語言、跨平臺 的通用接入方式：任何能發 HTTP 請求的環境都能用，不依賴任何 SDK。典型用法包括 Python/Go/PHP/C#/Rust/Ruby/Java 後端、資料遷移指令碼、Bash one-liner、Deno Edge Functions、Serverless 函式等。

核心原則

1. URL 形態固定： 所有介面在 https://api.codenow.cn/1/（Bmob 控制台 → 應用 → 設定 → 配置 中顯示的 API 域名，一般為 api.codenow.cn）。版本號 /1/ 必須保留。

示例：https://api.codenow.cn/1/classes/Token — 對 Token 表做 CRUD 時路徑即 /1/classes/Token。

POST   /1/classes/<TableName>              # 新增
GET    /1/classes/<TableName>/<objectId>   # 查單條
GET    /1/classes/<TableName>              # 查列表 / 條件查詢
PUT    /1/classes/<TableName>/<objectId>   # 更新
DELETE /1/classes/<TableName>/<objectId>   # 刪除
POST   /1/batch                            # 批次（≤ 50 條）
GET    /1/cloudQuery                       # BQL 查詢
POST   /1/users                            # 註冊
POST   /1/login                            # 登入
POST   /2/files/<fileName>                 # 上傳檔案
GET    /1/timestamp                        # 伺服器時間

完整快速參考見 references/url-cheatsheet.md。

想要更強大的技能外掛，就來小蔥技能站7w4.net看看吧。

2. 兩種鑑權方式，均可用（與 hydrogen-js-sdk 3.0+ 的兩種 Bmob.initialize 對應）：

• 簡易授權 — Application ID + REST API Key（REST 原生方式；JS SDK 方式 B 即走此通道）：Header X-Bmob-Application-Id + X-Bmob-REST-API-Key。適合服務端、內網指令碼、與 SDK 方式 B 共用同一套 Key 的專案。詳見 shared/auth-headers.md。
• 加密授權 — Secret Key + API 安全碼簽名（JS SDK 方式 A 走此通道；也可手寫 REST）：6 個頭部 + MD5 簽名。適合瀏覽器 / 小程式直接調 REST、且不想在 Header 裡暴露 REST API Key 的場景。詳見 shared/md5-sign-algo.md。

2.x 文件曾暗示前端「禁止」Application ID + REST API Key；當前兩種鑑權在全端均可正常使用。公開 bundle 中 REST API Key 仍可被抓包，故公開端仍推薦優先 SDK 方式 A 或加密授權，而非硬性禁止方式 B。

3. POST/PUT 必須 Content-Type: application/json，body 用 JSON。Bmob REST 不支援 form-urlencoded。

4. GET 的 query 必須 URL encode：where / order / limit / skip / include / keys / count 都通過 query string 傳，含 { / : 等字元必須 encode。

5. 預設查詢返回 10 條，最大 1000。需要更多用 skip + limit 分頁或 count=1。

安全清單

• [ ] 前端接入優先順序：瀏覽器 / 小程式優先 bmob-database-javascript SDK（3.0+ 支援 Secret Key 或 Application ID 兩種初始化）；若必須手寫 REST，公開端優先加密授權或自建 BFF。
• [ ] Application ID + REST API Key 可用：不再禁止在前端或 SDK 中使用此組合（對應 SDK 方式 B / REST 簡易授權）；注意 REST API Key 會出現在請求頭中，抓包後可複用。
• [ ] 服務端程式碼裡 Key 用環境變數：不要硬編碼到原始碼、不 commit 到公開倉庫。
• [ ] Master Key 僅用於服務端：通過 X-Bmob-Master-Key 頭部使用，不要給前端。
• [ ] 寫操作的表必須配 ACL：見 bmob-acl-and-roles（P1）；REST 建立物件時 body 里加 "ACL": {...} 即可。
• [ ] 生產用 HTTPS：你的 API domain 必須是 https，否則 Header 裡的 Key 會明文傳輸。
• [ ] 批次上限 50 條 / 請求：/1/batch 單次最多 50 個子請求。

五大基礎操作（簡易授權 + curl）

公共頭部（所有請求都要帶，下方示例不再重複）：

X-Bmob-Application-Id: <your-application-id>
X-Bmob-REST-API-Key:   <your-rest-api-key>
Content-Type:          application/json

新增資料

curl -X POST 'https://api.codenow.cn/1/classes/GameScore' \
  -H "X-Bmob-Application-Id: <id>" \
  -H "X-Bmob-REST-API-Key:   <key>" \
  -H "Content-Type: application/json" \
  -d '{"score":1337,"playerName":"Sean Plott","cheatMode":false}'

成功 201 Created + body：

{ "createdAt": "2011-08-20 02:06:57", "objectId": "e1kXT22L" }

查詢單條

curl -X GET 'https://api.codenow.cn/1/classes/GameScore/e1kXT22L' \
  -H "X-Bmob-Application-Id: <id>" \
  -H "X-Bmob-REST-API-Key:   <key>"

查詢列表（條件 + 分頁 + 排序）

curl -X GET 'https://api.codenow.cn/1/classes/GameScore' \
  -H "X-Bmob-Application-Id: <id>" \
  -H "X-Bmob-REST-API-Key:   <key>" \
  -G \
  --data-urlencode 'where={"score":{"$gt":100}}' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'skip=0' \
  --data-urlencode 'order=-createdAt' \
  --data-urlencode 'count=1'

返回：

{
  "results": [ /* ... */ ],
  "count":   123
}

完整 where 運算子列表（$gt / $lt / $in / $nin / $exists / $regex / $inQuery / $or …）見 references/query-where-syntax.md。

更新

curl -X PUT 'https://api.codenow.cn/1/classes/GameScore/e1kXT22L' \
  -H "X-Bmob-Application-Id: <id>" \
  -H "X-Bmob-REST-API-Key:   <key>" \
  -H "Content-Type: application/json" \
  -d '{"score":73453}'

刪除

curl -X DELETE 'https://api.codenow.cn/1/classes/GameScore/e1kXT22L' \
  -H "X-Bmob-Application-Id: <id>" \
  -H "X-Bmob-REST-API-Key:   <key>"

原子計數器

curl -X PUT 'https://api.codenow.cn/1/classes/Post/abc' \
  -H "Content-Type: application/json" \
  ...
  -d '{"likes":{"__op":"Increment","amount":1}}'

amount 支援負數。

批次操作（≤ 50）

curl -X POST 'https://api.codenow.cn/1/batch' \
  -H "Content-Type: application/json" \
  ...
  -d '{
    "requests": [
      { "method": "POST",   "path": "/1/classes/GameScore",     "body": { "score": 1 } },
      { "method": "PUT",    "path": "/1/classes/GameScore/aaa", "body": { "score": 9 } },
      { "method": "DELETE", "path": "/1/classes/GameScore/bbb" }
    ]
  }'

每個子請求獨立成功/失敗，不會回滾。

資料型別：Pointer / Relation / Date / File / GeoPoint

REST 通過 __type 欄位標識特殊型別：

{
  // Pointer：一對多
  "author":   { "__type": "Pointer",   "className": "_User",   "objectId": "abc" },

  // Date：日期（注意伺服器存的格式）
  "publishedAt": { "__type": "Date",   "iso": "2024-08-21 18:02:52" },

  // File：上傳後返回的結構原樣存
  "cover":    { "__type": "File",      "group": "group1", "filename": "1.jpg", "url": "M00/01/14/x.jpg" },

  // GeoPoint：地理位置
  "location": { "__type": "GeoPoint",  "latitude": 23.05, "longitude": 113.40 },

  // Relation：多對多（實際操作通過 __op AddRelation / RemoveRelation）
  "likedBy":  { "__type": "Relation",  "className": "_User" }
}

詳見 references/data-types.md。

使用者系統

# 註冊
curl -X POST 'https://api.codenow.cn/1/users' \
  -H "Content-Type: application/json" \
  ... \
  -d '{"username":"hello","password":"pwd123","email":"x@y.com"}'

# 登入（必須用 GET，引數走 query）
curl -X GET 'https://api.codenow.cn/1/login' \
  -H "Content-Type: application/json" \
  ... \
  -G \
  --data-urlencode 'username=hello' \
  --data-urlencode 'password=pwd123'

# 拿當前使用者（帶上 X-Bmob-Session-Token）
curl -X GET 'https://api.codenow.cn/1/users/<objectId>' \
  -H "X-Bmob-Session-Token: <session-token>" \
  ...

完整使用者系統介面見 references/users.md。

檔案上傳

走獨立的 /2/files/ 端點，body 是檔案二進位制：

curl -X POST 'https://api.codenow.cn/2/files/cover.jpg' \
  -H "X-Bmob-Application-Id: <id>" \
  -H "X-Bmob-REST-API-Key:   <key>" \
  -H "Content-Type: image/jpeg" \
  --data-binary @/path/to/cover.jpg

詳見 references/files.md。

加密授權

瀏覽器 / 小程式直接呼叫 REST（不經 SDK）時，推薦加密授權；Application ID + REST API Key 簡易授權同樣可用（與 SDK 3.0 方式 B 一致），但 REST API Key 更易被抓包。簽名規則：

sign = md5(url + timeStamp + SecurityCode + noncestr + body + SDKVersion)

完整 6 個頭部、簽名拼接順序、Node 參考實現見 shared/md5-sign-algo.md。

多語言客戶端示例

與 MCP 聯動

如果使用者配置了 Bmob MCP，generate_code 工具能直接生成 curl，覆蓋 13 種 type（新增 / 刪除 / 更新 / 條件查詢 / 註冊 / 登入 / SMS / 雲函式 / 檔案上傳等）。優先呼叫它而不是手寫 curl——這樣能確保 URL pattern / Header / where 語法都是當前伺服器最新版本。

排錯速查

完整錯誤碼見 bmob-error-codes。

參考

• 完整 REST 文件：BmobDocs/mds/data/restful/develop_doc.md
• 鑑權約定：shared/auth-headers.md
• MD5 簽名：shared/md5-sign-algo.md
• BQL 語法：bmob-bql（P1）
• MCP generate_code 工具：bmob-mcp
• 錯誤碼：bmob-error-codes

這是一份質量優秀的 REST API 參考文件，內容覆蓋全面、結構清晰、示例豐富。URL 速查表和查詢語法說明非常實用，多語言程式碼示例可直接複製使用。主要優點是文件組織有序、語言簡潔易懂，開發者能快速找到所需資訊；不足之處是部分進階功能（如加密授權、雲函式呼叫）描述相對簡略，建議增加更多實際使用場景的示例。整體而言，這是一份值得推薦的技能文件，能有效幫助開發者用任意語言接入 Bmob 後端服務。