undefined

Custom objects API

Custom Objects module allows to build the own data structure or schema and provides a flexibility for those who needs to go beyond the standard solutions. Data schema is defined in ConnectyCube dashboard and is called as 'class'.

To start using Custom Objects module, data schema should be created first.

Field types supported in Custom object module:

  • Integer
  • String
  • Float
  • Boolean
  • Array
  • File
  • Location (Array of [, ])
  • Date

Create data schema

Data schema can be created in the ConnectyCube dashboard within 'Custom' module. Go to 'Add' options and select 'Add new class' from the list:

Create data schema via dashboard

Input a Class name and identify at least one field to add in the Class by specifying data type:

Create a new class

Click on 'Create class' to complete creation of data schema. Newly created class is now available and contains the following data:

  • ID - record indentifier generated by system automatically
  • User ID - identifier of user who created a record
  • Parent ID - by default is null
  • Field_1 - field defined in a scheme
  • Field_2 - field defined in a scheme
  • ...
  • Field_N - field defined in a scheme
  • Created_at - date and time when a record is created

Created class

Create a new record

Create a new record with the defined parameters in the class. Fields that weren't defined in the request but available in the scheme (class) will have null values.

Endpoint
POST https://api.connectycube.com/data/{class_name}
Parameters

Any custom parameter (field in the schema) can be used in the request to identify a new record.

Request example
curl -X POST \
-H "CB-Token: <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"full_name": "Nadine Collier", "age": "41", "job": "accountant", "country_of_birth": "Germany"}' \
https://api.connectycube.com/data/profile
Response
{
    "_id":"5c09798aca8bf468ab8d2936",
    "_parent_id":null,
    "age":41,
    "country_of_birth":"Germany",
    "created_at":1544124810,
    "full_name":"Nadine Collier",
    "job":"accountant",
    "updated_at":1544124810,
    "user_id":47592,
    "permissions":
        {
            "read":{
                    "access":"open"
            },
            "update":{
                    "access":"owner"
            },
            "delete":{
                    "access":"owner"
            }
        }
}

Create multi records

Create several new records in the class. Fields that weren't defined in the request but available in the scheme would have null values.

Endpoint
POST https://api.connectycube.com/data/{class_name}/multi
Set parameters

Format: {"record": {"0": {"field_1": "value", "field_2": "value"}, "1": {"field_1": "value", "field_2": "value"}}}

Note: the first record_number is always 0.

Request example
curl -X POST \
-H "CB-Token: <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"record": {"0": {"age": "11"}, "1": {"age": "55"}}}' \
https://api.connectycube.com/data/profile/multi
Response
{
    "class_name":"profile",
    "items":[
        {
            "_id":"5c098d1fca8bf4291e8d220b",
            "_parent_id":null,
            "age":11,
            "country_of_birth":null,
            "created_at":1544129823,
            "full_name":null,
            "job":null,
            "updated_at":1544129823,
            "user_id":47592,
            "permissions":
                {
                    "read":{
                        "access":"open"
                    },
                    "update":{
                        "access":"owner"
                    },
                    "delete":{
                        "access":"owner"
                    }
                }
        },
        {
            "_id":"5c098d1fca8bf4291e8d220c",
            "_parent_id":null,
            "age":55,
            "country_of_birth":null,
            "created_at":1544129823,
            "full_name":null,
            "job":null,
            "updated_at":1544129823,
            "user_id":47592,
            "permissions":
                {
                    "read":{
                        "access":"open"
                    },
                    "update":{
                        "access":"owner"
                    },
                    "delete":{
                        "access":"owner"
                    }
                }
        }
    ]
}

Record with permissions

Access control list (ACL) is a list of permissions attached to some object. An ACL specifies which users have an access to objects, as well as what operations are allowed on given objects. Each entry in a typical ACL specifies a subject and an operation. ACL models may be applied to collections of objects as well as to individual entities within the system's hierarchy.

Adding the Access Control list is only available withinh the Custom objects module.

Permissions scheme

ConnectyCube permission scheme contains five permissions levels:

  • Open (open) - any user within application can access the record(s) in the class and is allowed to perform actions with a record
  • Owner (owner) - only Owner (user who created a record) is allowed to perform action with a record
  • Not allowed (not_allowed) - no one (except the Account Administrator) can proceed with a chosen action
  • Open for groups (open_for_groups) - users which have a specified tag(s) will be included in the group which is allowed to perform actions with a record. Several groups can be specified (number of groups is not limited).
  • Open for users ids (open_for_users_ids) - only users with listed IDs can perform actions with a record.

Actions to work with entity:

  • Create - create a new record
  • Read - retrieve information about a record and view it in the read-only mode
  • Update - update any parameter of the chosen record that can be updated by user
  • Delete - delete a record

To set a permission schema for the Class, go to ConnectyCube dashboard and find a required class within Custom objects module Click on ‘Edit permission’ button to open permissions schema to edit.

Edit permissions

Each listed action has a separate permission level to select. The exception is a 'Create' action that isn’t available for 'Owner' permission level.

Edit permissions levels

Permission levels

Two access levels are available in the ConnectyCube: access to Class and access to Record.

Only one permission schema can be applied for the record. Using the Class permission schema means that Record permission schema won’t be affected on a reсord.

Class entity

Class is an entity that contains records. Class can be created via ConnecyCube dashboard only withing Custom oblects module. Operations with Class entity are not allowed in API.

All actions (Create, Read, Update and Delete) that are available for the ‘Class’ entity are also applicable for all records within a class.

Default Class permission schema is using while creating a class:

  • Create: Open
  • Read: Open
  • Update: Owner
  • Delete: Owner

To enable applying Class permissions for any of actions type, 'Use Class permissions' check box should be ticked. It means that record permission schema (if any) won’t be affected on a record.

Record entity

Record is an entity within the Class in the Custom Objects module that can be created in ConnectyCube dashaboard and via API. Each record within a Class has its own permission level. Unlike Class entity, 'Not allowed' permission level isn't available for a record as well as only three actions are available to work with a record - read, update and delete.

Default values for Record permission scheme:

  • Read: Open
  • Update: Owner
  • Delete: Owner

To set a separate permission scheme for a record, open a record to edit and click on 'Set permissions on record' button:

Set permissions for record

Define the permission level for each of available actions:

Define the permission level for a record

Create a record with permissions

To create a new record with permissions, add permissions[action_name][access] parameter to 'Create a record' request.

Endpoint
POST https://api.connectycube.com/data/{class_name}
Parameters
Permissions Syntax Example
Open / Owner "permissions": {"action_name": {"access": "owner"} "permissions": {"read": {"access": "owner"}
Open for users IDs "permissions": {"action_name": {"access": "open_for_users_ids", "ids": ["{id_1}","{id_2}"]} "permissions": {"update": {"access": "open_for_users_ids", "ids": ["51941","51943"]}}
Open for groups "permissions": {"action_name": {"access": "open_for_groups", "groups": ["group_1","group_2"]}} "permissions": {"delete": {"access": "open_for_groups", "groups": ["officers","assistants"]}}
Request example
curl -X POST \
-H "Content-Type: application/json" \
-H "CB-Token: <TOKEN>" \
-d '{"full_name": "Jacelyn Millard", "age":"25", "country_of_birth": "India", "permissions": {"read": {"access":"owner"}, "update": {"access": "open_for_users_ids", "ids": ["51941","51943"]}, "delete": {"access": "open_for_groups", "groups": ["officers","assistants"]}}}' \
https://api.connectycube.com/data/profile
Response
{
    "_id":"5c0d6d8cca8bf4291e8d3d1b",
    "_parent_id":null,
    "age":25,
    "avatar":null,
    "country_of_birth":"India",
    "created_at":1544383884,
    "full_name":"Jacelyn Millard",
    "job":null,
    "updated_at":1544383884,
    "user_id":47592,
    "permissions":
        {
            "read":
                {
                    "access":"owner"
                },
            "update":
                {
                    "access":"open_for_users_ids",
                    "users_ids":
                        [
                            "51941","51943"
                        ]
                },
            "delete":
                {
                    "access":"open_for_groups",
                    "users_groups":
                        [
                            "officers","assistants"
                        ]
                }
        }
}

Retrieve records by IDs

Retrieve records by specifying their identifiers.

Endpoint
GET https://api.connectycube.com/data/{class_name}/{record_id1},{record_id2}
Request example
curl -X GET \
-H "CB-Token: <TOKEN>" \
https://api.connectycube.com/data/profile/5c09798aca8bf468ab8d2936,5c097c45ca8bf468ab8d294e
Response
{
    "class_name":"profile",
    "items":[
        {
            "_id":"5c09798aca8bf468ab8d2936",
            "_parent_id":null,
            "age":41,
            "country_of_birth":"Germany",
            "created_at":1544124810,
            "full_name":"Nadine Collier",
            "job":"accountant",
            "updated_at":1544124810,
            "user_id":47592,
            "permissions":
                {
                    "read":{
                        "access":"open"
                    },
                    "update":{
                        "access":"owner"
                    },
                    "delete":{
                        "access":"owner"}
                    }
        },
        {
            "_id":"5c097c45ca8bf468ab8d294e",
            "_parent_id":null,
            "age":25,
            "country_of_birth":"Sweden",
            "created_at":1544125509,
            "full_name":"Lacey Idec",
            "job":"secretary",
            "updated_at":1544125521,
            "user_id":47592,
            "permissions":
                {
                    "read":{
                        "access":"open"
                    },
                    "update":{
                        "access":"owner"
                    },
                    "delete":{
                        "access":"owner"
                }
            }
        }
    ]
}

Retrieve records within a class

Search records within the particular class.

Note: If you are sorting records by time, use the _id field. It is indexed and will be much faster than sorting by created_at field.

Endpoint
GET https://api.connectycube.com/data/{class_name}
Options to apply
1. Sorting
Parameter Applicable to type Description
{field_name} all types Search records by the specified field
{field_name}[search_operator] all types Search records by the specified field with applying filters to filter the query result set
sort_asc all types Sorting the query result set in ascending order
sort_desc all types Sorting the query result set in descending order
skip integer Skip N records in the query result set. By default, all found records are shown
limit integer Set a limit for displaying the query results. Default and max values - 100. To show the last record only, set limit=-1 in the request
count integer Number of records returned in the query result set
output[include] all types Fields to include in the query result set
output[exclude] all types Fields to exclude from the query result set
near Location Search records in a defined radius (in meters) starting from the current position. Format: {field_name}[near]=longitude,latitude;radius

Example:

curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'sort_asc=age' \
https://api.connectycube.com/data/profile
2. Search criterias

Format: {field_name}[operator]={value}

Operator Applicable to types Description Data to return
gt
  • integer
  • float
  • greater than Records where the specified parameter has values greater than specified in the request
    lt
  • integer
  • float
  • less than Records where the specified parameter has values less than specified in the request
    gte
  • integer
  • float
  • greater than or equal to Records where the specified parameter has values greater than or equal to the specified in the request
    lte
  • integer
  • float
  • less than or equal to Records where the specified parameter has values less than or equal to the specified in the request
    ne
  • integer
  • float
  • string
  • boolean
  • not equal Records where the specified parameter has values not equal to the specified in the request
    in
  • integer
  • float
  • string
  • in array Records with the specified values to found in the array
    nin
  • integer
  • float
  • string
  • not in array Specified records not included in the array
    all
  • array
  • all contained in array All records that correspond to parameters specified in the request
    or
  • integer
  • float
  • string
  • one or another parameter Records with one of the specified parameters
    ctn
  • integer
  • float
  • string
  • contain Returns all records where field contains adjusted substring

    Example:

    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    -d 'age[gt]=28' \
    https://api.connectycube.com/data/profile
    3. Aggregation operators
    Parameter Applicable to types Description
    {field_name}[calc]={operator}
  • integer
  • float
  • avg, min, max, sum should be used with group_by operator
    group_by={field_name}
  • integer
  • float
  • string
  • boolean
  • group_by works similar to SQL GROUP BY operator, should be used with calc operator

    Example:

    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    -d 'age[calc]=avg&group_by=country_of_birth' \
    https://api.connectycube.com/data/profile
    Request example
    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    -d 'age[gt]=28&sort_desc=full_name' \
    https://api.connectycube.com/data/profile
    Response
    {
        "class_name":"profile",
        "skip":0,
        "limit":100,
        "items":
            [
                {
                    "_id":"5c0d7458ca8bf43a5b8cf487",
                    "_parent_id":"",
                    "age":41,
                    "avatar":null,
                    "country_of_birth":"India",
                    "created_at":1544385624,
                    "full_name":"Zach Whitehouse",
                    "job":"Operation officer",
                    "updated_at":1544385624,
                    "user_id":47592
                },
                {
                    "_id":"5c0d4f95ca8bf4291e8d3c2d",
                    "_parent_id":"",
                    "age":50,
                    "avatar":null,
                    "country_of_birth":"USA",
                    "created_at":1544376213,
                    "full_name":"Nadine Collier",
                    "job":null,
                    "updated_at":1544381152,
                    "user_id":47592
                }
            ]
    }

    Retrieve record by ID to view its permissions

    To retrieve the records to view their permissions use the parameter ‘permissions’ and set it as true ‘permissions=1’. Use GET method.

    Note: record permissions are checking while request is processing. Only owner has an ability to view a record’s permissions.

    Endpoint
    GET https://api.connectycube.com/data/{class_name}/{record_id}
    Parameters
    Parameter Description
    permissions To retrieve the records to view their permissions use the parameter ‘permissions’ and set it as true permissions=1
    Request example
    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    -d 'permissions=1' \
    https://api.connectycube.com/data/profile/5bf7da90ca8bf42dae037dea
    Response
    {
        "permissions":
            {
                "read":
                    {
                        "access":"owner"
                    },
                "update":
                    {
                        "access":"open_for_users_ids",
                        "users_ids":
                            [
                                "51941","51943"
                            ]
                    },
                "delete":
                    {
                        "access":"open_for_groups",
                        "users_groups":
                            [
                                "officers","assistants"
                            ]
                    }
            },
        "record_id":"5c0d6d8cca8bf4291e8d3d1b"
    }

    Update record by ID

    Update record data by specifying its ID.

    Endpoint
    PUT https://api.connectycube.com/data/{class_name}/{record_id}
    Parameters
    Parameter Description
    field_name Name of the fields to update
    Special update operators
    Operator Applicable to types Description Syntax
    inc
  • integer
  • float
  • Increment a value in the field to specified one. Value can be either positive or negative (i.e. decrement operation) "inc": {"field_name": "value"}
    pull arrays Remove specified value from the array "pull": {"field_name": "value"}
    pull with filter arrays Remove all found elements from array after applying a filter "pull": {"field_name": {"operator": "value"}}
    pull_all arrays Remove all specified values from the array "pull_all": {"field_name": ["value_1", "value_2"]}
    pop arrays Remove the last element in the array. To remove the first element, set parameter to '-1' "pop": {"groups": "1"}
    push arrays Append specified values to the array "push": {"field_name": ["value_1", "value_2"]}
    add_to_set arrays Add a value to the array if this value is not in the array yet. Existing value will be skipped "add_to_set": {"field_name": ["value_1", "value_2"]}}' \
    Update array element by index operator arrays Update array element by specifying element index. The first one in the array is always '0' "field_name": {"index_1": "value", "index_2": "value"}

    To nullify an existing value, specify "null" for application/x-www-/form-urlencoded and null for application/json content-type (depends on the format used in the request). For numeric fields (Integer & Float) there is a special increment operator - inc that increments or decrements a numeric field.

    Request example
    curl -X PUT \
    -H "CB-Token: <TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{"age": "22", "job": "technical director"}' \
    https://api.connectycube.com/data/profile/5c097e8cca8bf4291e8d219f
    Response
    {
        "_id":"5c097e8cca8bf4291e8d219f",
        "_parent_id":null,
        "age":22,
        "country_of_birth":"Poland",
        "created_at":1544126092,
        "full_name":"Barret Campbell",
        "job":"technical director",
        "updated_at":1544128080,
        "user_id":47592,
        "permissions":
            {
                "read":{
                    "access":"open"
                },
                "update":{
                    "access":"owner"
                },
                "delete":{
                    "access":"owner"
                }
        }
    }

    Update records by criteria

    Update records found by the specified search criteria with a new parameter(s).

    Endpoint
    PUT https://api.connectycube.com/data/{class_name}/by_criteria
    Parameters
    Parameter Description Syntax
    search_criteria[field_name][operator] search_criteria - required on the beginning, field_name - name of the fields to use for search, operator - search operator to find the records "search_criteria": {"field": {"operator": "value"}}
    Search criterias
    Operator Applicable to types Description Data to return
    gt
  • integer
  • float
  • greater than Records where the specified parameter has values greater than specified in the request
    lt
  • integer
  • float
  • less than Records where the specified parameter has values less than specified in the request
    gte
  • integer
  • float
  • greater than or equal to Records where the specified parameter has values greater than or equal to the specified in the request
    lte
  • integer
  • float
  • less than or equal to Records where the specified parameter has values less than or equal to the specified in the request
    ne
  • integer
  • float
  • string
  • boolean
  • not equal Records where the specified parameter has values not equal to the specified in the request
    in
  • integer
  • float
  • string
  • contained in array Records with the specified values to found in the array
    nin
  • integer
  • float
  • string
  • not contained in array Records with the specified values that are not in the array
    all array all contained IN array All records that correspond to parameters specified in the request
    or
  • integer
  • float
  • string
  • one or another Records found by one of the specified parameters
    ctn
  • integer
  • float
  • string
  • contain Return all records that contain a specified data
    Request example
    curl -X PUT \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{"search_criteria": {"age":{"lt":30}}, "country_of_birth":"Iran"}' \
    https://api.connectycube.com/data/profile/by_criteria
    Response
    {
        "class_name":"profile",
        "skip":0,
        "limit":100,
        "total_found":1,
        "items":[
            {
                "_id":"5c09798aca8bf468ab8d2936",
                "_parent_id":null,
                "age":22,
                "country_of_birth":"Iran",
                "created_at":1544124810,
                "full_name":"Nadine Collier",
                "job":"accountant",
                "updated_at":1544367921,
                "user_id":47592,
                "permissions":
                    {
                        "read":{
                            "access":"open"
                        },
                        "update":{
                            "access":"open"
                        },
                        "delete":{
                            "access":"open"
                        }
                    }
            }
        ]
    }

    Update multi records

    Update several records within a class by specifying new values.

    Endpoint
    PUT https://api.connectycube.com/data/{class_name}/multi
    The format of query
    {"record": {"record_number": {"id": "value", "field_1": "value", "field_2":"value"}}}

    where:

    • record_number - record number in the query. Numbering begins with '1'
    • field_name - field in Custom Object to update
    Request example
    curl -X PUT \
    -H "Content-Type: application/json" \
    -H "CB-Token: <TOKEN>" \
    -d '{"record": {"1": {"id": "5c0d4f95ca8bf4291e8d3c2d", "country_of_birth": "USA", "age":"50"}, "2": {"id": "5c0d625aca8bf43a5b8cf3de", "country_of_birth": "Lithuania", "age":"28"}, "3": {"id": "5c0d625aca8bf43a5b8cf111", "country_of_birth": "Greece", "age":"35"}}}' \
    https://api.connectycube.com/data/profile/multi
    Response
    {
        "class_name":"profile",
        "not_found":
            {
                "ids":["5c0d625aca8bf43a5b8cf111"]
            },
        "items": [
            {
                "_id":"5c0d4f95ca8bf4291e8d3c2d",
                "_parent_id":"",
                "age":50,
                "avatar":null,
                "country_of_birth":"USA",
                "created_at":1544376213,
                "full_name":"Nadine Collier",
                "job":null,
                "updated_at":1544381152,
                "user_id":47592,
                "permissions":
                    {
                        "read": {
                            "access":"open"
                        },
                        "update": {
                            "access":"owner"
                        },
                        "delete": {
                            "access":"owner"
                        }
                    }
            },
            {
                "_id":"5c0d625aca8bf43a5b8cf3de",
                "_parent_id":"",
                "age":28,
                "avatar":null,
                "country_of_birth":"Lithuania",
                "created_at":1544381018,
                "full_name":"Georgia Barny",
                "job":"Managing officer",
                "updated_at":1544381152,
                "user_id":47592,
                "permissions":
                    {
                        "read": {
                            "access":"open"
                        },
                        "update": {
                            "access":"owner"
                        },
                        "delete": {
                            "access":"owner"
                        }
                    }
            }
        ]
    }

    Delete record by ID

    Delete a record from a class by record identifier.

    Endpoint
    DELETE https://api.connectycube.com/data/{class_name}/{id}
    Request example
    curl -X DELETE \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/data/profile/5c090e0fe588ce59fff873df
    Response
    200 OK

    Delete several records by their IDs

    Delete several records from a class by specifying their identifiers. If one or more records can not be deleted, an appropriate error is shown for that record(s).

    Endpoint
    DELETE https://api.connectycube.com/data/{class_name}/{id_1},{id_2},{id_3}
    Request example
    curl -X DELETE \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/data/profile/5bf7da90ca8bf42dae037dea,5bf7db7cca8bf45ff403449c,5bf7d621ca8bf45ff4034463
    Response
    {
      "SuccessfullyDeleted": {
        "ids": [
          "5c097c45ca8bf468ab8d294e"
        ]
      },
      "WrongPermissions": {
        "ids": [
          "5c097e8cca8bf4291e8d219f"
        ]
      },
      "NotFound": {
        "ids": [
          "55c09798aca8bf468ab8d2936"
        ]
      }
    }
    

    Delete records by criteria

    Delete records from the class by specifying a criteria to find records to delete.

    Endpoint
    DELETE https://api.connectycube.com/data/{class_name}/by_criteria
    Query format
    '{field_name}[operator]={value}'
    Search criterias
    Operator Applicable to types Description Data to return
    gt
  • integer
  • float
  • greater than Records where the specified parameter has values greater than specified in the request
    lt
  • integer
  • float
  • less than Records where the specified parameter has values less than specified in the request
    gte
  • integer
  • float
  • greater than or equal to Records where the specified parameter has values greater than or equal to the specified in the request
    lte
  • integer
  • float
  • less than or equal to Records where the specified parameter has values less than or equal to the specified in the request
    ne
  • integer
  • float
  • string
  • boolean
  • not equal Records where the specified parameter has values not equal to the specified in the request
    in
  • integer
  • float
  • string
  • in array Users with the specified IDs
    nin
  • integer
  • float
  • string
  • not in array Records not specified in the array
    all array all contained in array All records that correspond to parameters specified in the request
    or
  • integer
  • float
  • string
  • one or another Records with one of the specified parameters
    ctn
  • integer
  • float
  • string
  • contain Returns all records where field contains adjusted substring
    Request example
    curl -X DELETE \
    -H "CB-Token: <TOKEN>" \
    -d 'age[gte]=41' \
    https://api.connectycube.com/data/profile/by_criteria
    Response
    {
        "total_deleted": 2
    }

    Relations

    Objects (records) in different classes can be linked with a _parent_id field. If record from the Class 1 is pointed with a record from Class 2 via its _parent_id, the _parent_id field will contain an ID of a record from the Class 2.

    If a record from the Class 2 is deleted, all its children (records of the Class 1 with _parent_id field set to the Class 2 record ID) will be automatically deleted as well.

    The linked children can be retrieved with _parent_id={id_of_parent_class_record} parameter.