Version: 1.0.0

• OpenAPI Spec

PostgreSQL HTTP API

Function Introduction

The Data API of CloudBase PostgreSQL database is based on the open-source PostgREST. For more documentation, please refer to the official PostgREST documentation.

Public schema only

Currently the REST API only supports the public schema: you can only access tables, views, and functions in the public schema, and cannot access or switch to other schemas (such as auth or storage).

To read or write data outside the public schema, use Execute SQL statements or the SQL editor in the console instead.

Request Domain

The request URL format is: https://{envId}.api.tcloudbasegateway.com/v1/rdb/rest/{table}

• envId is the environment ID
• table is the table name, which must be in the public schema

Integration Guide

To call the following APIs, you need to pass an AccessToken in format Authorization: Bearer <token>. For how to obtain the Access token, refer to the documentation.

Request Encoding

Please perform URL encoding before making requests, for example:

Original request

curl -i -X GET 'https://{{host}}/v1/rdb/rest/course?select=name,position&name=like.%张三%&title=eq.文章标题'

Encoded request

curl -i -X GET 'https://{{host}}/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'

Request Headers and Response Headers

Request Header	Parameters	Description	Example
Accept	Supports application/json, application/vnd.pgrst.object+json	Controls data return format	Accept: application/json
Content-Type	Supports application/json, application/vnd.pgrst.object+json	Return	Content-Type: application/json
Prefer	Characteristic values that operations depend on	return=representation Write operation, returns data body and headers return=minimal Write operation, returns only headers without data body, default type for write operations count=exact Read operation, specifies count calculation resolution=merge-duplicates Upsert operation, merges conflicting items resolution=ignore-duplicates Upsert operation, ignores conflicting items	Prefer: return=representation
Preference-Applied	Prefer type used in request	Response information uses Prefer from request, will return corresponding characteristic information, may have default values in certain cases	Preference-Applied: return=representation
Content-Range	Pagination information	When querying with Prefer: count=exact, pagination information like 0-1/2 will be returned, where 0 indicates starting position, 1 indicates offset, and 2 indicates total count (Note: The starting position and offset here are not the meanings of offset and limit keywords in PostgreSQL, but refer to the data position after query, usually used with limit) When specifying return=representation or return=minimal (default) for write operations, pagination information like -/2 will be returned, where 2 indicates the number of affected rows	Content-Range: 0-1/2

Error Codes and HTTP Status Codes

Error Code	HTTP Status Code	Description
INVALID_PARAM	400	Invalid request parameter
INVALID_REQUEST	400	Invalid request content: missing permission fields, SQL execution exceptions, etc.
INVALID_REQUEST	406	Does not meet single record return constraint
PERMISSION_DENIED	401、403	Authentication failed: returns 401 if identity authentication fails, returns 403 if authorization fails
RESOURCE_NOT_FOUND	404	Database instance or table information not found
SYS_ERR	500	System internal error
OPERATION_FAILED	503	Failed to establish database connection
RESOURCE_UNAVAILABLE	503	Database unavailable due to certain reasons

Data Return

1. For all POST, PATCH, DELETE, request header with Prefer: return=representation indicates there is a response body, absence indicates no response package, only response headers
2. Response body of POST, PATCH, DELETE is usually JSON array type []. If request header specifies Accept: application/vnd.pgrst.object+json, then JSON object type {} will be returned
3. If specifying Accept: application/vnd.pgrst.object+json, but the data amount is greater than 1, an error will be reported