bmob-database-restful

Bmob Database — REST API

Bmob REST API is a cross-language, cross-platform universal access method: any environment that can send HTTP requests can use it, without depending on any SDK. Typical uses include Python/Go/PHP/C#/Rust/Ruby/Java backends, data migration scripts, Bash one-liners, Deno Edge Functions, Serverless functions, etc.

Core Principles

1. Fixed URL form: All APIs at https://api.codenow.cn/1/(the API domain shown in the Bmob console → App → Settings → Configuration, usually api.codenow.cn). The version number /1/ must be retained.

Example:https://api.codenow.cn/1/classes/Token — when doing CRUD on the Token table, the path is /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                        # 服务器时间

For the complete quick reference, see references/url-cheatsheet.md。

2. Two authentication methods, both usable(corresponding to the two 3.0+ of hydrogen-js-sdk Bmob.initialize ):

Simple authorization — Application ID + REST API Key(REST native method; JS SDK Method B uses this channel): Header X-Bmob-Application-Id + X-Bmob-REST-API-Key. Suitable for server-side, intranet scripts, and projects sharing the same set of Keys with SDK Method B. See shared/auth-headers.md。
Encrypted authorization — Secret Key + API security code signature（JS SDK Method A uses this channel; REST can also be written manually): 6 headers + MD5 signature. Suitable for scenarios where the browser / mini program directly calls REST, and you do not want to expose the REST API Key in the Header. See shared/md5-sign-algo.md。

2.x documentation once implied that the frontend was "forbidden" from using Application ID + REST API Key;currently both authentication methods work normally on all ends. In public bundles the REST API Key can still be captured, so on public ends it is stillrecommendedto prefer SDK Method A or encrypted authorization, rather than hard-forbidding Method B.

3. POST/PUT must Content-Type: application/json, body uses JSON. Bmob REST does not support form-urlencoded.

4. GET query must be URL encoded：where / order / limit / skip / include / keys / count are all passed via query string, including { / : and other characters must be encoded.

5. Default query returns 10 records, maximum 1000. If more are needed, use skip + limit pagination or count=1。

Security Checklist

Frontend integration priority: Browser / mini program prefer bmob-database-javascript SDK (3.0+ supports Secret Key or Application ID two initialization methods); if REST must be written manually, on public ends prefer encrypted authorization or a self-built BFF.
Application ID + REST API Key are usable: it is no longer forbidden to use this combination in the frontend or SDK (corresponding to SDK Method B / REST simple authorization); note that the REST API Key will appear in request headers and can be reused after packet capture.
Use environment variables for Keys in server-side code: do not hardcode them into source code, do not commit them to public repositories.
Master Key is only for server-side use: used via the X-Bmob-Master-Key header,do notgive it to the frontend.
Tables with write operations must have ACL configured: see bmob-acl-and-roles(P1); when creating objects via REST, add "ACL": {...} in the body.
Use HTTPS in production: your API domain must be https, otherwise the Key in the Header will be transmitted in plaintext.
Batch limit 50 records / request：/1/batch At most 50 subrequests per call.

FAQ

Cross-platform Q&A:shared/faq.md。

Anti-patterns

See shared/anti-patterns.md. Client-side key points: Master Key is server-side only; on the public side, prefer encrypted authorization or the SDK, and do not expose the REST Key.

Five Basic Operations (Simple Authorization + curl)

Common headers (required for all requests; not repeated in the examples below):

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

Add Data

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}'

Success 201 Created + body：

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

Query a Single Record

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

Query a List (conditions + pagination + sorting)

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'

Returns:

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

Complete list of where operators ($gt / $lt / $in / $nin / $exists / $regex / $inQuery / $or ...) see references/query-where-syntax.md。

Update

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}'

Delete

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

Atomic Counter

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

amount supports negative numbers.

Batch Operations (≤ 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" }
    ]
  }'

Each subrequest succeeds or fails independently;no rollback。

Data Types: Pointer / Relation / Date / File / GeoPoint

REST identifies special types via the __type field:

{
  // 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" }
}

See references/data-types.md。

User System

# 注册
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>" \
  ...

For the complete user system interface, see references/users.md。

File Upload

Uses a separate /2/files/ endpoint, with the body as the file binary:

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

See references/files.md。

Encrypted Authorization

Browser / Mini ProgramWhen calling REST directly(without going through the SDK),recommendedencrypted authorization; Application ID + REST API Key simple authorization also works (consistent with SDK 3.0 method B), but the REST API Key is easier to capture via packet sniffing. Signing rules:

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

For all 6 headers, the signature concatenation order, and a Node reference implementation, see shared/md5-sign-algo.md。

Multi-language Client Examples

Language	Example
Python（requests）	`references/lang-snippets/python.md`
Go（net/http）	`references/lang-snippets/go.md`
PHP（Guzzle）	`references/lang-snippets/php.md`
C#（HttpClient）	`references/lang-snippets/csharp.md`

Integration with MCP

If the user has configured Bmob MCP，generate_code tool can directly generate curl, covering 13 types (add / delete / update / conditional query / register / login / SMS / cloud function / file upload, etc.). Prefer calling it instead of writing curl by hand—this ensures the URL pattern / Header / where syntax are all the latest version of the current server.

Advanced Reference

Topic	Path
End-to-end scenarios (migration, files, ACL, etc.)	`shared/recipes/`
BmobDocs synchronized code snippets	`references/snippets/`
where syntax	`references/query-where-syntax.md`
User / File	`references/users.md`、`references/files.md`

Troubleshooting Quick Reference

For cross-platform symptoms, first check shared/faq.md。

HTTP	code	Meaning
401	—	Wrong App ID or REST API Key; or wrong encrypted authorization signature
400	101	Object does not exist / incorrect username or password
400	105	Illegal field name or reserved field (`objectId`/`createdAt`/`updatedAt`/`ACL`）
400	106	Incorrect Pointer format
400	107	Incorrect JSON format / Content-Type is not application/json
400	117	Latitude / longitude out of range
400	122	User permission verification failed (ACL)
400	202	username is already in use
400	209	mobilePhoneNumber is already in use
400	211	User is not logged in / login has expired
400	401	Duplicate value in unique index
400	402	where exceeds byte limit
400	10076	QPS limit exceeded
500	—	Temporary server failure, retry later

For complete error codes, see bmob-error-codes。

Reference

Complete REST documentation:BmobDocs/mds/data/restful/develop_doc.md
Authentication conventions:shared/auth-headers.md
MD5 signature:shared/md5-sign-algo.md
BQL syntax:bmob-bql（P1）
MCP generate_code Tools:bmob-mcp
Error codes:bmob-error-codes