Concept

The Datably API lets you programmatically access all Datably features directly via a programming language such as JavaScript. It is based on PHP-CRUD-API, the TreeQL reference implementation in PHP.

Documentation

API Path

Show Technical Info - check this option in the Database stack to display the API Path in Preview.

Limitations

These limitation and constrains apply:
  • Primary keys should either be auto-increment (from 1 to 2^53) or UUID
  • Composite primary and composite foreign keys are not supported
  • Complex writes (transactions) are not supported
  • Complex queries calling functions (like "concat" or "sum") are not supported
  • Database must support and define foreign key constraints
  • SQLite cannot have bigint typed auto incrementing primary keys
  • SQLite does not support altering table columns (structure)

TreeQL, a pragmatic GraphQL

TreeQL allows you to create a "tree" of JSON objects based on your SQL database structure (relations) and your query.

It is loosely based on the REST standard and also inspired by json:api.
CRUD + List
The example "posts" table has only a a few fields:
posts
=====
id     
title  
content
created
The CRUD + List operations below target this table.
Create
If you want to create a record the request can be written in URL format as:
POST <api_path>/records/posts
You have to send a body containing:
{
    "title": "Black is the new red",
    "content": "This is the second post.",
    "created": "2022-03-06T21:34:01Z"
}
And it will return the value of the primary key of the newly created record:
2
Read
To read a record from this table the request can be written in URL format as:
GET <api_path>/records/posts/1
Where "1" is the value of the primary key of the record that you want to read. It will return:
{
    "id": 1
    "title": "Hello world!",
    "content": "Welcome to the first post.",
    "created": "2022-03-05T20:12:56Z"
}
On read operations you may apply joins.
Update
To update a record in this table the request can be written in URL format as:
PUT <api_path>/records/posts/1
Where "1" is the value of the primary key of the record that you want to update. Send as a body:
{
    "title": "Adjusted title!"
}
This adjusts the title of the post. And the return value is the number of rows that are set:
1
Delete
If you want to delete a record from this table the request can be written in URL format as:

DELETE <api_path>/records/posts/1
And it will return the number of deleted rows:
1
List
To list records from this table the request can be written in URL format as:
GET <api_path>/records/posts/1
This will return:
{
    "records":[
        {
            "id": 1,
            "title": "Hello world!",
            "content": "Welcome to the first post.",
            "created": "2022-03-05T20:12:56Z"
        }
    ]
}
On list operations you may apply filters and joins.
Filters
Filters provide search functionality, on list calls, using the "filter" parameter. You need to specify the column name, a comma, the match type, another commma and the value you want to filter on. These are supported match types:
  • "cs": contain string (string contains value)
  • "sw": start with (string starts with value)
  • "ew": end with (string end with value)
  • "eq": equal (string or number matches exactly)
  • "lt": lower than (number is lower than value)
  • "le": lower or equal (number is lower than or equal to value)
  • "ge": greater or equal (number is higher than or equal to value)
  • "gt": greater than (number is higher than value)
  • "bt": between (number is between two comma separated values)
  • "in": in (number or string is in comma separated list of values)
  • "is": is null (field contains "NULL" value)
You can negate all filters by prepending a "n" character, so that "eq" becomes "neq".
Examples:
GET <api_path>/records/categories?filter=name,eq,Internet
GET <api_path>/records/categories?filter=name,sw,Inter
GET <api_path>/records/categories?filter=id,le,1
GET <api_path>/records/categories?filter=id,ngt,1
GET <api_path>/records/categories?filter=id,bt,0,1
GET <api_path>/records/categories?filter=id,in,0,1
Output:
{
    "records":[
        {
            "id": 1
            "name": "Internet"
        }
    ]
}
Multiple Filters
Filters can be a by applied by repeating the "filter" parameter in the filter string, for example:
GET <api_path>/records/categories?filter=id,gt,1&filter=id,lt,3
This will request all records "where id > 1 and id < 3". If you wanted "where id = 2 or id = 4" you should write:
GET <api_path>/records/categories?filter1=id,eq,2&filter2=id,eq,4
As you see we added a number to the "filter" parameter to indicate that "OR" instead of "AND" should be applied. Note that you can also repeat "filter1" and create an "AND" within an "OR". Since you can also go one level deeper by adding a letter (a-f) you can create almost any reasonably complex condition tree.
Column selection
By default all columns are selected. With the "include" parameter you can select specific columns. You may use a dot to separate the table name from the column name. Multiple columns should be comma separated. An asterisk ("*") may be used as a wildcard to indicate "all columns". Similar to "include" you may use the "exclude" parameter to remove certain columns:
GET <api_path>/records/categories/1?include=name
GET <api_path>/records/categories/1?include=categories.name
GET <api_path>/records/categories/1?exclude=categories.id
Output:
    {
        "name": "Internet"
    }
Ordering
With the "order" parameter you can sort. By default the sort is in ascending order, but by specifying "desc" this can be reversed:
GET <api_path>/records/categories?order=name,desc
GET <api_path>/records/categories?order=id,desc&order=name
Output:
    {
        "records":[
            {
                "id": 3
                "name": "Web development"
            },
            {
                "id": 1
                "name": "Internet"
            }
        ]
    }
NB: You may sort on multiple fields by using multiple "order" parameters. You can not order on "joined" columns.

Navigio Icon

Made by Navigio