Database APIs

This is a general example of Deskree REST APIs. You can download it as a postman collection from the API Docs page of your project.

base_url is equal to https://YOUR_PROJECT_ID.api.deskree.com/api/v1/

Note that the Users table is a special table and does not allow POST or DELETE requests since account creation/removal is handled by AUTH APIs. For more information, view our Users Table guide.

If you receive 412 error, it means that an index needs to be created for your query. Deskree handles this process automatically. For more information, visit the Indexes page.

Get list of all rows in TABLE_NAME

GET base_url/TABLE_NAME

Get data from the database table

Query Parameters

Name	Type	Description
where	Array of Where Objects	Where object describing query parameters
sorted[param]	String	How to sort response results: what parameter to sort by Must be used with sorted[param] parameter
sorted[how]	asc | desc	How to sort response results: ascending vs descending Must be used with sorted[param] parameter
page	Number	Page number to navigate to if the response is paginated
limit	Number	Number of results per page if the response is paginated Default: 50
includes	Array of string	An array of columns with one-to-one or one-to-many references that you would like to include in your response. For one-to-one reference the value will be returned as an object containing the includes in place of the reference value. For one-to-many reference the value will be returned as an array of objects containing the includes in place of the reference value.

Headers

Name	Type	Description
Authorization	Bearer	idToken of your user returned from any sign-up or a sign-in request from AUTH APIs

200: OK Example response

{
    "data": [
        {
            "uid": "iaijasdiadsi14in",
            "attributes": {
                "name": "T-Shirt",
                "price": 10,
                "category": {
                    "uid": "n10234b901489bwduih1dw91",
                    "name": "clothing"
                },
                "createdAt": "2022-08-22T16:04:49-04:00",
                "updatedAt": "2022-08-22T16:04:51-04:00"
            }
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "limit": 1,
        "includesCount": 1
    }
}

500: Internal Server Error Returns an server error message

{
    "errors": [
        {
            "code": "500",
            "title": "Internal Server Error",
            "detail": "Error processing your request"
        }
    ]
}

403: Forbidden Return an error message related to authentication

{
    "errors": [
        {
            "code": "403",
            "title": "Forbidden",
            "detail": "Token is not valid"
        }
    ]
}

Get row by UID from TABLE_NAME

GET base_url/TABLE_NAME/ROW_UID

Get data from the database table by UID

Query Parameters

Name	Type	Description
includes	Array of strings	An array of columns with one-to-one or one-to-many references that you would like to include in your response. For one-to-one reference the value will be returned as an object containing the includes in place of the reference value. For one-to-many reference the value will be returned as an array of objects containing the includes in place of the reference value.

Headers

Name	Type	Description
Authorization	Bearer	YOUR_TOKEN

200: OK Example response

{
    "data": {
        "name": "T-Shirt",
        "price": 10,
        "category": {
            "uid": "n10234b901489bwduih1dw91",
            "name": "clothing"
        },
        "createdAt": "2022-08-22T16:04:49-04:00",
        "updatedAt": "2022-08-22T16:04:51-04:00"
    },
    "meta": {
        "total": 1,
        "page": 1,
        "limit": 1,
        "includesCount": 1
    }
}Get data from the database table by UID

500: Internal Server Error Returns an server error message

{
    "errors": [
        {
            "code": "500",
            "title": "Internal Server Error",
            "detail": "Error processing your request"
        }
    ]
}

403: Forbidden Returns an error message related to authentication

{
    "errors": [
        {
            "code": "403",
            "title": "Forbidden",
            "detail": "Token is not valid"
        }
    ]
}

404: Not Found Returns not found error

{
    "data": null,
    "errors": [
        {
            "code": "404",
            "title": "Not found",
            "detail": "Requested object not found"
        }
    ]
}

Create a new row in TABLE_NAME

POST base_url/TABLE_NAME

Create an object in the database

Query Parameters

Name	Type	Description
skipFileExceptions	Boolean	If set to true will skip file upload exceptions in the back end and will return 200 even if there is an error during downloading/uploading of files. Read more

Headers

Name	Type	Description
Authorization	Bearer	YOUR_TOKEN
Content-Type*	String	application/json

200: OK Returns the object added to the database

{
    "data": {
        "uid": "tTvKpi6E7N68Xv8RJOug"
        "name": "Hat",
        "price": 12,
        "image": "",
        "createdAt": "2022-08-22T16:04:49-04:00",
        "updatedAt": "2022-08-22T16:04:51-04:00"
    },
    "meta": {
        "total": 1,
        "page": 1,
        "limit": 1,
        "includesCount": 0
    },
    "info": {
        "action": "post",
        "webhooksTriggered": 0
    }
}

422: Unprocessable Entity Returns an error message of what went wrong

{
    "errors": [
        {
            "propertyErrors": [],
            "typeErrors": [],
            "propertyMissingErrors": [
                {
                    "code": "422",
                    "title": "Unprocessable Entry",
                    "detail": "Required property name from the 'products' database table is missing"
                }
            ]
        }
    ]
}

500: Internal Server Error Returns an server error message

{
    "errors": [
        {
            "code": "500",
            "title": "Internal Server Error",
            "detail": "Error processing your request"
        }
    ]
}

403: Forbidden Return an error message related to authentication

{
    "errors": [
        {
            "code": "403",
            "title": "Forbidden",
            "detail": "Token is not valid"
        }
    ]
}

Update row by UID in TABLE_NAME

PATCH base_url/TABLE_NAME/ROW_UID

Query Parameters

Name	Type	Description
skipFileExceptions	boolean	If set to true will skip file upload exceptions in the back end and will return 200 even if there is an error during downloading/uploading of files. Read more

Headers

Name	Type	Description
Authorization	Bearer	YOUR_TOKEN
Content-Type*	String	application/json

200: OK Returns the object updated to the database

{
    "data": {
        "uid": "tTvKpi6E7N68Xv8RJOug"
        "name": "Hat",
        "price": 12,
        "image": "",
        "createdAt": "2022-08-22T16:04:49-04:00",
        "updatedAt": "2022-08-22T16:04:51-04:00"
    },
    "meta": {
        "total": 1,
        "page": 1,
        "limit": 1,
        "includesCount": 0
    },
    "info": {
        "action": "patch",
        "webhooksTriggered": 0
    }
}

422: Unprocessable Entity Returns an error message of what went wrong

{
    "errors": [
        {
            "propertyErrors": [],
            "typeErrors": [],
            "propertyMissingErrors": [
                {
                    "code": "422",
                    "title": "Unprocessable Entry",
                    "detail": "Required property name from the 'products' database table is missing"
                }
            ]
        }
    ]
}

500: Internal Server Error Returns an server error message

{
    "errors": [
        {
            "code": "500",
            "title": "Internal Server Error",
            "detail": "Error processing your request"
        }
    ]
}

403: Forbidden Returns an error message related to authentication

{
    "errors": [
        {
            "code": "403",
            "title": "Forbidden",
            "detail": "Token is not valid"
        }
    ]
}

404: Not Found Returns not found error

{
    "data": null,
    "errors": [
        {
            "code": "404",
            "title": "Not found",
            "detail": "Requested object not found"
        }
    ]
}

Delete row by UID in TABLE_NAME

DELETE base_url/TABLE_NAME/ROW_UID

Delete an object in the database. Note: If you delete an object the associated file will automatically be deleted in storage as well.

Headers

Name	Type	Description
Authorization	Bearer	YOUR_TOKEN

200: OK Returns data object with the uid and the location of the deleted object

{
    "data": {
        "uid": "E9s6pTHnFdzilQ6rTD3Z",
        "resource": "tests"
    },
    "meta": {},
    "info": {
        "action": "delete",
        "webhooksTriggered": 0
    }
}

500: Internal Server Error Returns an server error message

{
    "errors": [
        {
            "code": "500",
            "title": "Internal Server Error",
            "detail": "Error processing your request"
        }
    ]
}

403: Forbidden Returns an error message related to authentication

{
    "errors": [
        {
            "code": "403",
            "title": "Forbidden",
            "detail": "Token is not valid"
        }
    ]
}

404: Not Found Returns not found error

{
    "data": null,
    "errors": [
        {
            "code": "404",
            "title": "Not found",
            "detail": "Requested object not found"
        }
    ]
}

Where object

Note that UID cannot be used in the attribute field. If you want to get an item by UID, you can use the Get by UID endpoint instead.

Field	Data Type	Description
attribute	string	Column name that you would like to query by
operator	< | > | == | != | <= | >= | array-contains | array-contains-any | in | not-in	An operator to perform the query
value	any	Value of the query

GET Response Structure

Parameters

Field	Data Type	Description
data	Array of objects	Array of data objects
meta	Object	Object containing metadata

Database Object Parameters

Field	Data Type	Description
uid	string	UID of a database item
attributes	Object	Object containing all database item values

Metadata Parameters

Field	Data Type	Description
total	number	Total number of items in the database
page	number	Current page number
limit	number	Current limit per page
includesCount	number	Number of additional requests for the includes operations

POST, PATCH, and DELETE Response Structure

Parameters

Field	Data Type	Description
data	Object	Object containing all database item values
meta	Object	Object containing metadata
info	Object	Object containing operation information

Metadata Parameters

Field	Data Type	Description
total	number	Total number of items in with the given UID Always equal to 1
page	number	Current page number Always equal to 1
limit	number	Current limit per page Always equal to 1
includesCount	number	Number of additional requests for the includes operations Always equal to 0

Info Parameters

Field	Data Type	Description
action	string	Operation name
webhooksTriggered	number	Number of webhooks triggered by the operation

Helpful Resources

• How to upload files?
• How to use permissions?