FairCom REST API Reference

REST API V1 Reference

The REST API includes resources for performing navigational (NoSQL) operations on entities such as tables, records, indexes, queries, and errors.

Check your FairCom DB REST server port. Most often it will be 8443, but could be 8080 if your server is not set up for SSL encryption.

You can test this by using one of the following URLs in your browser:

Your browser will need to be configured to allow sites with self-signed certificates in order to see this page. In production, you would replace these with your own certificates signed by a CA.

• No SSL: http://localhost:8080/ctree/api/v1/openapi
• With SSL: https://localhost:8443/ctree/api/v1/openapi

Note: The REST port is configured with the cthttpd.json file in the config directory. Use the keyword listening_http_port or listening_https_port as described in HTTP Plug-in in the FairCom DB Developer Guide. If your port is not 8443, you will need to change the URLs in this tutorial accordingly.

OpenAPI

This resource represents the OpenAPI specification for this REST API.

Type: GET

URL: /ctree/api/v1/openapi

For a complete overview of the API, view the OpenAPI specification available at these URLs:

• OpenAPI without SSL: http://localhost:8080/ctree/api/v1/openapi
• OpenAPI with SSL: https://localhost:8443/ctree/api/v1/openapi

The above URLs assume the localhost is the system that has FairCom DB installed. From other systems, the URL is http://<ip number>:8080/ctree/api/v1/openapi

These URLs can be used in this OpenAPI viewer:

https://petstore.swagger.io/

To learn more about OpenAPI, please follow this link:

https://github.com/OAI/OpenAPI-Specification

JSON Supported in REST API

The REST API supports a JSON field type. c-treeDB also supports the ability to index JSON field contents.

To index a JSON field, specify the JSON field name in the "name" attribute and the key, type and length of the attribute that needs to be indexed using the "key", "type" and "size" attributes in the index definition.

Example:

{
"fields": [{
"name": "custinfo",
"key": "name",
"type": "string",
"size": 50
}],
"unique": false
}

When inputting a record with a JSON field, the JSON field value can be specified as a JSON type. This is the highly recommended method:

{
"custid": "1000",
"custinfo": {
"name": "Bryan Williams"
}
}

Although not recommended, when inputting a record with a JSON field, the JSON field value can be specified as a string representing the JSON to insert:

"{\"custom\":\"1000\",\"custinfo\":{\"name\":\"Bryan Williams\" }"

Below is an example on how to query the JSON content once indexed:

{
"find": {
"operator": ">=",
"fields": {
"custinfo": {"name":"a"}
}
},
"select": [
"custid",
"custinfo"
]
}

When creating a table with a JSON field, the field length specified is ignored and the JSON field content can be as large as 2GB.

JSON Types

Because JSON supports a very precise list of types, the following types are included in JSON support:

• integer - signed integer with size 1, 2, 4; any other size is considered as 8
• unsigned - unsigned integer with size as integer
• string - a string with the specified size
• float - same as double
• double - double precision floating point, size forced to 8
• boolean - Boolean value, size forced to 1

REST default date and time string format

The c-treeDB default date and time format is set to:

• CTDATE_MDCY
• CTTIME_HMST

This results in the following string format:

MM/DD/CCYY h|hh:mm:ss.ttt (24 h) (ttt are milliseconds). Hours can be either one or two digits. (See c-treeDB Date Formats and c-treeDB Time Formats for details and alternative formats.)

The node expects and returns dates, times, and timestamps in the above string format.

Errors

Errors are returned in the body in the form of:

{

"_errorCode": 0,

"_errorMessage": ""

}