Special Considerations

Encoding Query and Body Parameters

Calls to the resource endpoint usually involves sending query and/or body parameters, usually enclosed in brackets {}. Everything between and including the brackets {} must be encoded. While some clients automatically encode the URL and the body, in many other cases it may remain your responsibility to do the encoding. Your programming language may provide a way for encoding strings. Various interactive web based encoders are also available and can be found using a search engine.

As an example encoded {“where”:”Name=’Mike'”} is %7B%22where%22%3A%22Name%3D’Mike’%22%7D and encoded {“Status”:”Updated”} is %7B%22Status%22%3A%22Updated%22%7D.

Autogenerated unique fields

When adding a new field using POST /v3/tables or POST /v3/tables/{tableName}/fields,
note that the following autogenerated field types must be created as unique:

• GUID
• RandomID
• Autonumber
• PrefixedAutonumber

For these field types, you must set the Unique property to true.
If you omit the property or attempt to set it to false, the request will return an error.

Limits 

The following limits apply to REST API operations: 

• A call can return a maximum of 1,000 records. 
• The maximum length of a request URI is 2047 characters. 

Only HTTPS Allowed

Calls to Caspio REST API URLs must be made using the HTTPS protocol.

PK_ID Fields

In addition to user-defined fields, all Caspio tables and views include a system-defined field called PK_ID. In tables, PK_ID is a long integer, while in views, it is a string containing a comma-separated list of the source tables’ PK_ID values. This field is automatically created and maintained by Caspio—you cannot delete, modify, or update it, either through the Caspio interface or the REST API.

The PK_ID field is included in REST API responses when table records are retrieved. To display the PK_ID values for your records within Caspio, open the table design, add a new field with the Formula data type, and use [@field:PK_ID] as the formula. In Datasheet view, the PK_ID values will be displayed in the new field.

Password Fields

Password fields are special data type fields that are meant for storing  encrypted values. You cannot obtain the value stored in password fields. All requests that attempt to get their values via Select or in other ways such as in Criteria, cause an error. When all fields of a table or view are returned via “Select *” or empty field list, password fields are skipped.

Password fields can be set to their initial value during an Insert operation. However, their values cannot be changed using the standard Update method. A special password update method is available to change the value of password fields.

List data type formatting

You can update List data type fields in table or view records using either list item IDs or the actual list values. The REST API accepts the following formats for POST and PUT operations: 

IDs 

• Arrays: [1, 2] 
• String lists: “1,2” 
• Stringified arrays: “[1,2]” 

Values 

• Arrays: [“A”, “B”] 
• String lists: “\”A\”,\”B\”” 
• Stringified arrays: “[\”A\”,\”B\”]” 

When passing values rather than IDs, note the following rules: 

• All values must be provided as strings.
• List String comparisons are case-insensitive and must match the defined list values. 
• List Number comparisons are numeric, so only the numeric value matters.
• List Date comparisons are date/time comparisons; values must be valid US-format dates or sortable ISO-like dates (yyyy-MM-dd hh:mm:ss or yyyy-MM-ddThh:mm:ss). 

In REST API V3, list values must represent a valid JSON array, even when enclosed in a string literal.

Response Date Format

All dates in Caspio REST API response are in ISO 8601 format.

Alternatives to PUT and DELETE Methods

If PUT and DELETE methods are prohibited in your client, you can use the custom header X-HTTP-Method-Override to make such requests using POST. To do this, just add the following header to a POST request. For example:

Parameter Name:  X-HTTP-Method-Override
Parameter Value: PUT    or   DELETE

“Created by” and “Modified by”

Objects created or modified through REST API operations will be stamped with the following value in “Created by” and “Modified by” fields: “API Profile (<Profile name>)”. This helps determine that a change was performed using REST API rather than by a Caspio platform user.