http-api-cloudbase

## Standalone Install Note If this environment only installed the current skill, start from the CloudBase main entry and use the published `cloudbase/references/...` paths for sibling skills. - CloudBase main entry: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md` - Current skill raw source: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/http-api/SKILL.md` Keep local `references/...` paths for files that ship with the current skill directory. When this file points to a sibling skill such as `auth-tool` or `web-development`, use the standalone fallback URL shown next to that reference. ## Activation Contract ### Use this first when - The request comes from Android, iOS, Flutter, React Native, non-Node backends, or admin scripts that must call official CloudBase APIs via raw HTTP. - The task is to consume CloudBase platform endpoints, not to build a new HTTP service on CloudBase. ### Read before writing code if - The platform does not support a CloudBase SDK, or the user explicitly asks for HTTP API integration. - The user says "HTTP API" but it is unclear whether they mean official CloudBase endpoints or their own business API. ### Then also read - Auth configuration -> `../auth-tool/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-tool/SKILL.md`) - MySQL MCP management -> `../relational-database-tool/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/relational-database-tool/SKILL.md`) - Your own HTTP service on CloudBase -> `../cloud-functions/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloud-functions/SKILL.md`) or `../cloudrun-development/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudrun-development/SKILL.md`) ### Do NOT use for - CloudBase Web SDK flows, mini program SDK flows, or MCP-driven management tasks. - Building your own HTTP service or REST API on CloudBase. ### Common mistakes / gotchas - Treating Web SDK examples as valid for native Apps. - Guessing endpoints without reading OpenAPI definitions. - Confusing official CloudBase HTTP APIs with your own function or CloudRun endpoint. - Mixing raw HTTP API integration with MCP management logic. ### Minimal checklist - Read [HTTP API Routing Checklist](checklist.md) before implementation. ## When to use this skill Use this skill whenever you need to call **CloudBase platform features** via **raw HTTP APIs**, for example: - Non-Node backends (Go, Python, Java, PHP, etc.) - Integration tests or admin scripts that use curl or language HTTP clients - Direct database operations via 关系型数据库 RESTful API (MySQL/PostgreSQL) - Cloud function invocation via HTTP - Any scenario where SDKs are not available or not preferred Do **not** use this skill for: - Frontend Web apps using `@cloudbase/js-sdk` (use **CloudBase Web** skills) - Node.js code using `@cloudbase/node-sdk` (use **CloudBase Node** skills) - Authentication flows (use **CloudBase Auth HTTP API** skill for auth-specific endpoints) ## How to use this skill (for a coding agent) 1. **Clarify the scenario** - Confirm this code will call HTTP endpoints directly (not SDKs). - Ask for: - `env` – CloudBase environment ID - Authentication method (AccessToken, API Key, or Publishable Key) - Confirm which CloudBase feature is needed (database, functions, storage, etc.). - **For user authentication**: If no specific method is requested, **always default to Phone SMS Verification** - it's the most user-friendly and secure option for Chinese users. 2. **Determine the base URL** - Use the correct domain based on region (domestic vs. international). - Default is domestic Shanghai region. 3. **Set up authentication** - Choose appropriate authentication method based on use case. - Add `Authorization: Bearer <token>` header to requests. 4. **Reference OpenAPI Swagger documentation** - **MUST use `searchKnowledgeBase` tool** to get OpenAPI specifications - Use the tool with `mode=openapi` and specify the `apiName`: - `mysqldb` - 关系型数据库 RESTful API (MySQL/PostgreSQL) - `nosql` - NoSQL RESTful API (文档型数据库) - `functions` - Cloud Functions API - `auth` - Authentication API - `cloudrun` - CloudRun API - `storage` - Storage API - `ai_model` - AI 大模型接入 API - Example: `searchKnowledgeBase({ mode: "openapi", apiName: "mysqldb" })` - Parse the returned YAML content to understand exact endpoint paths, parameters, request/response schemas - Never invent endpoints or parameters - always reference the swagger documentation --- ## Overview CloudBase HTTP API is a set of interfaces for accessing CloudBase platform features via HTTP protocol, supporting database, user authentication, cloud functions, cloud hosting, cloud storage, AI, and more. ## OpenAPI Swagger Documentation **⚠️ IMPORTANT: Always use `searchKnowledgeBase` tool to get OpenAPI Swagger specifications** Before implementing any HTTP API calls, you should: 1. **Use `searchKnowledgeBase` tool to get OpenAPI documentation**: ``` searchKnowledgeBase({ mode: "openapi", apiName: "<api-name>" }) ``` 2. **Available API names**: - `mysqldb` - 关系型数据库 RESTful API (MySQL/PostgreSQL) - `nosql` - NoSQL RESTful API (文档型数据库) - `functions` - Cloud Functions API - `auth` - Authentication API - `cloudrun` - CloudRun API - `storage` - Storage API - `ai_model` - AI 大模型接入 API 3. **Parse and use the swagger documentation**: - Extract exact endpoint paths and HTTP methods - Understand required and optional parameters - Review request/response schemas - Check authentication requirements - Verify error response formats 4. **Never invent API endpoints or parameters** - always base your implementation on the official swagger documentation. ## Prerequisites Before starting, ensure you have: 1. **CloudBase environment created and activated** 2. **Authentication credentials** (AccessToken, API Key, or Publishable Key) ## Authentication and Authorization CloudBase HTTP API requires authentication. Choose the appropriate method based on your use case: ### AccessToken Authentication **Applicable environments**: Client/Server **User permissions**: Logged-in user permissions **How to get**: Use `searchKnowledgeBase({ mode: "openapi", apiName: "auth" })` to get the Authentication API specification ### API Key **Applicable environments**: Server **User permissions**: Administrator permissions - **Validity**: Long-term valid - **How to get**: Get from [CloudBase Platform/ApiKey Management Page](https://tcb.cloud.tencent.com/dev?#/identity/token-management) > ⚠️ Warning: Tokens are critical credentials for identity authentication. Keep them secure. API Key must NOT be used in client-side code. ### Publishable Key **Applicable environments**: Client/Server **User permissions**: Anonymous user permissions - **Validity**: Long-term valid - **How to get**: Get from [CloudBase Platform/ApiKey Management Page](https://tcb.cloud.tencent.com/dev?#/identity/token-management) > 💡 Note: Can be exposed in browsers, used for requesting publicly accessible resources, effectively reducing MAU. ## API Endpoint URLs CloudBase HTTP API uses unified domain names for API calls. The domain varies based on the environment's region. ### Domestic Regions For environments in **domestic regions** like Shanghai (`ap-shanghai`), use: ```text https://{your-env}.api.tcloudbasegateway.com ``` Replace `{your-env}` with the actual environment ID. For example, if environment ID is `cloud1-abc`: ```text https://cloud1-abc.api.tcloudbasegateway.com ``` ### International Regions For environments in **international regions** like Singapore (`ap-singapore`), use: ```text https://{your-env}.api.intl.tcloudbasegateway.com ``` Replace `{your-env}` with the actual environment ID. For example, if environment ID is `cloud1-abc`: ```text https://cloud1-abc.api.intl.tcloudbasegateway.com ``` ## Using Authentication in Requests Add the token to the request header: ```http Authorization: Bearer <access_token/apikey/publishable_key> ``` :::warning Note When making actual calls, replace the entire part including angle brackets (`< >`) with your obtained key. For example, if the obtained key is `eymykey`, fill it as: ```http Authorization: Bearer eymykey ``` ::: ## Usage Examples ### Cloud Function Invocation Example ```bash curl -X POST "https://your-env-id.api.tcloudbasegateway.com/v1/functions/YOUR_FUNCTION_NAME" \ -H "Authorization: Bearer <access_token/apikey/publishable_key>" \ -H "Content-Type: application/json" \ -d '{"name": "张三", "age": 25}' ``` For detailed API specifications, always download and reference the OpenAPI Swagger files mentioned above. ## 关系型数据库 RESTful API (PostgREST 风格) > **适用于 MySQL 和 PostgreSQL**：两者均基于 PostgREST 风格暴露 REST API，端点格式和请求语义一致。 提供关系型数据库（MySQL / PostgreSQL）的 HTTP 操作接口。 ### Base URL Patterns Support three domain access patterns: 1. `https://{envId}.api.tcloudbasegateway.com/v1/rdb/rest/{table}` 2. `https://{envId}.api.tcloudbasegateway.com/v1/rdb/rest/{schema}/{table}` 3. `https://{envId}.api.tcloudbasegateway.com/v1/rdb/rest/{instance}/{schema}/{table}` Where: - `envId` is the environment ID - `instance` is the database instance identifier - `schema` is the database name - `table` is the table name If using the system database, **recommend pattern 1**. ### Request Headers | Header | Parameter | Description | Example | |--------|-----------|-------------|---------| | Accept | `application/json`, `application/vnd.pgrst.object+json` | Control data return format | `Accept: application/json` | | Content-Type | `application/json`, `application/vnd.pgrst.object+json` | Request content type | `Content-Type: application/json` | | Prefer | Operation-dependent feature values | - `return=representation` Write operation, return data body and headers<br>- `return=minimal` Write operation, return headers only (default)<br>- `count=exact` Read operation, specify count<br>- `resolution=merge-duplicates` Upsert operation, merge conflicts<br>- `resolution=ignore-duplicates` Upsert operation, ignore conflicts | `Prefer: return=representation` | | Authorization | `Bearer <token>` | Authentication token | `Authorization: Bearer <access_token>` | ### Query Records **GET** `/v1/rdb/rest/{table}` **Query Parameters**: - `select`: Field selection, supports `*` or field list, supports join queries like `class_id(grade,class_number)` - `limit`: Limit return count - `offset`: Offset for pagination - `order`: Sort field, format `field.asc` or `field.desc` **Example**: ```bash # Before URL encoding curl -X GET 'https://your-env.api.tcloudbasegateway.com/v1/rdb/rest/course?select=name,position&name=like.%张三%&title=eq.文章标题' \ -H "Authorization: Bearer <access_token>" # After URL encoding curl -X GET 'https://your-env.api.tcloudbasegateway.com/v1/rdb/rest/course?select=name,position&name=like.%%E5%BC%A0%E4%B8%89%&title=eq.%E6%96%87%E7%AB%A0%E6%A0%87%E9%A2%98' \ -H "Authorization: Bearer <access_token>" ``` **Response Headers**: - `Content-Range`: Data range, e.g., `0-9/100` (0=start, 9=end, 100=total) ### Insert Records **POST** `/v1/rdb/rest/{table}` **Request Body**: JSON object or array of objects > 💡 **Identity fields differ by database mode**: In PostgreSQL / CloudBase PG, do **not** use `_openid`. Prefer owner columns with `DEFAULT auth.uid()` (JWT `sub`) and omit the owner field from INSERT bodies. In legacy MySQL/NoSQL-oriented examples, `_openid` may be populated by the platform; do not copy that pattern into PG tables. **Example**: ```bash curl -X POST 'https://your-env.api.tcloudbasegateway.com/v1/rdb/rest/course' \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -H "Prefer: return=representation" \ -d '{ "name": "数学", "position": 1 }' ``` ### Update Records **PATCH** `/v1/rdb/rest/{table}` **Request Body**: JSON object with fields to update **Example**: ```bash curl -X PATCH 'https://your-env.api.tcloudbasegateway.com/v1/rdb/rest/course?id=eq.1' \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -H "Prefer: return=representation" \ -d '{ "name": "高等数学", "position": 2 }' ``` > ⚠️ **Important**: UPDATE requires a WHERE clause. Use query parameters like `?id=eq.1` to specify conditions. ### Delete Records **DELETE** `/v1/rdb/rest/{table}` **Example**: ```bash curl -X DELETE 'https://your-env.api.tcloudbasegateway.com/v1/rdb/rest/course?id=eq.1' \ -H "Authorization: Bearer <access_token>" ```