Custom Objects

Ask tech team
From QuickBlox Developers (API docs, code samples, SDK)
(Redirected from SimpleSample-ratings-ios)
Jump to: navigation, search

Contents

Module description

Custom Objects module provides flexibility to define any data structure(schema) you need. Schema is defined in QuickBlox Administration Panel. The schema is called Class and contains field names and their type.

Available types are:

  • Integer
  • String
  • Float
  • Boolean
  • Array
  • File
  • Location (array with 2 elements: longitude, latitude)

In the following example we will use class named MyScoreTable, which contains fields:

Field name Type
gameModeName String
scoreValue Integer
bonusCount Float
expertMode Boolean
_id* String (Record ID). It is a 12-byte type, constructed using:
  • a 4-byte value representing the seconds since the Unix epoch,
  • a 3-byte machine identifier,
  • a 2-byte process id, and
  • a 3-byte counter, starting with a random value.
created_at* Integer (contains Unix timestamp - date & time when record was created, filled automatically)
updated_at* Integer (contains Unix timestamp - date & time when record was updated, filled automatically)
user_id* Integer (contains API User ID, which created current record)
_parent_id* String (parent object's ID, related to Relations)

*These fields are pre-defined for all objects and may be included in GET query (i.e. filtering, without _id - there is separate request)


Create data schema

To start using Custom Objects module you should create your data schema. Go to admin.quickblox.com, Custom Objects module page and press Add new class button. 'Add new class' popup will appear.

Enter Class name, add any fields you want. Allow 7 types of fields:

  • Integer
  • Float
  • Boolean (true/false)
  • String
  • Array (of Integers, Floats, Booleans, Strings)
  • File
  • Location

COCreateClass.png

Press Create class button - new class will be created

COPredefinedFields.png

There are some predefined fields, that described in Custom Objects REST API Module description documentation.

To add record just press Add record button. 'Add new record' popup will appear. Fill any fields you want and press Add record button. New record will be added & shown in table.

API requests

URL HTTP Verb Action Description Success HTTP Status Code
/data/{class_name}/{record_id1},{record_id2}... GET Retrieve records by IDs 200
/data/{class_name} GET Retrieve records 200
/data/{class_name} POST Create new record 201
/data/{class_name}/{id} PUT Update record by ID 200
/data/{class_name}/{id} DELETE Delete record by ID 200

Retrieve records by IDs

Retrieve records with particular records ids

Request

curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable/51c9ab92535c12951b0032d6,51c9ab92535c12951b0032dd?output[exclude]=_id
curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable/51c9ab92535c12951b0032d6,51c9ab92535c12951b0032dd.json?output[exclude]=_id

Response

<?xml version="1.0" encoding="UTF-8"?>
<data type="array">
  <MyScoreTable>
    <_parent_id nil='true'/>
    <bonus-count type="float">66.86</bonus-count>
    <created-at type="integer">1344256366</created-at>
    <expert-mode type="boolean">true</expert-mode>
    <game-mode-name>ctf</game-mode-name>
    <score-value type="integer">9307</score-value>
    <updated-at type="integer">1344256366</updated-at>
    <user-id type="integer">457</user-id>
  </MyScoreTable>
  <MyScoreTable>
    <_parent_id nil='true'/>
    <bonus-count type="float">60.9</bonus-count>
    <created-at type="integer">1344256366</created-at>
    <expert-mode type="boolean">false</expert-mode>
    <game-mode-name>rage</game-mode-name>
    <score-value type="integer">7327</score-value>
    <updated-at type="integer">1344256366</updated-at>
    <user-id type="integer">981</user-id>
  </MyScoreTable>
</data>
{
   "class_name":"MyScoreTable",
   "skip":0,
   "limit":100,
   "items":[
      {
         "bonus_count":0.0,
         "created_at":1345448268,
         "expert_mode":false,
         "game_mode_name":"ds",
         "score_value":0,
         "updated_at":1350392824,
         "user_id":106,
         "_parent_id": null
      },
      {
         "game_mode_name":"ctf",
         "score_value":8247,
         "bonus_count":146.75,
         "expert_mode":true,
         "user_id":517,
         "_parent_id": null,
         "created_at":1344256366,
         "updated_at":1344256366
      }
   ]
}

Retrieve records

Search for records of particular class

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

Filters

The request can contain all, some or none of next filters.

Filter Applicable to types Usage example Description
{field_name} All types rating=2 Search records with field which contains exactly specified value
{field_name}[{search_operator}] All types rating[gt]=4 Search record with field which contains value according to specified value and operator
sort_asc All types sort_asc=field_name Search results will be sorted by specified field in ascending order
sort_desc All types sort_desc=field_name Search results will be sorted by specified field in descending order
skip Integer skip=100 Skip N records in search results. Useful for pagination. Default (if not specified): 0
limit Integer limit=50 Limit search results to N records. Useful for pagination. Default value - 100. Also can set 1000.If limit is equal to -1 only last record will be returned
count Integer count=1 Count search results. Response will contain only count of records found
output[include] All types output[exclude]=field_name1,field_name2 The output parameter takes the form of a record with a list of fields for inclusion or exclusion from the result set. output[include] specifies the fields to include. The _id field is, by default, included in the result set. To exclude the _id field from the result set, you need to specify in the output[exclude] value the exclusion of the _id field.
output[exclude] All types output[exclude]=field_name1,field_name2 The output parameter takes the form of a record with a list of fields for inclusion or exclusion from the result set. output[exclude] specifies the fields to exclude. The _id field is, by default, included in the result set. To exclude the _id field from the result set, you need to specify in the output[exclude] value the exclusion of the _id field.
near Location mylocation[near]=25.32,44.551;1000 Search records in a specific radius with current position in meters. Format: field_name[near]=longitude,latitude;radius

Search operators

The request can contain all, some or none of next search operators:

Combinations of operators are allowed (for example - score_value[gt]=100&score_value[lt]=1000&game_mode_name[in]=deathmatch,ctf)

Operator Applicable to types Usage example Description
lt Integer, Float score_value[lt]=1000 Less Than operator
lte Integer, Float score_value[lte]=850 Less Than or Equal to operator
gt Integer, Float bonus_count[gt]=2.45 Greater Than operator
gte Integer, Float bonus_count[gte]=56.443 Greater Than or Equal to operator
ne Integer, Float, String, Boolean game_mode_name[ne]=ctf Not Equal to operator
in Integer, Float, String game_mode_name[in]=deathmatch,rage Contained IN array operator
nin Integer, Float, String game_mode_name[nin]=survivor,crazy_nightmare Not contained IN array
all Array game_modes[all]=survivor,crazy ALL contained IN array
or Integer, Float, String 1.name[or]=sam,igor
2.name[or]=sam&lastname[or]=johnson
1.Will return records with name sam or igor
2.Will return records with name sam or lastname johnson
ctn String username[ctn]=son Will return all records where username field contains son substring

Aggregation operators

Next aggregation operators are for performing aggregation tasks:

Operator Applicable to types Usage example Description
{field_name}[calc]={operator} Integer, Float rating[calc]=min avg, min, max, sum can be used with group_by operator
group_by={field_name} Integer, Float, String, Boolean group_by=game_mode_name group_by works similar to SQL GROUP BY operator, should be used with calc operator


Request

curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable
curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable.json

Response

<?xml version="1.0" encoding="UTF-8"?>
<data type="array">
  <MyScoreTable>
    <_id>501fb96e957fb3454f000732</_id>
    <_parent_id nil='true'/>
    <bonus-count type="float">66.86</bonus-count>
    <created-at type="integer">1344256366</created-at>
    <expert-mode type="boolean">true</expert-mode>
    <game-mode-name>ctf</game-mode-name>
    <score-value type="integer">9307</score-value>
    <updated-at type="integer">1344256366</updated-at>
    <user-id type="integer">457</user-id>
  </MyScoreTable>
  ...
  <MyScoreTable>
    <_id>501fb96e957fb3454f00072e</_id>
    <_parent_id nil='true'/>
    <bonus-count type="float">60.9</bonus-count>
    <created-at type="integer">1344256366</created-at>
    <expert-mode type="boolean">false</expert-mode>
    <game-mode-name>rage</game-mode-name>
    <score-value type="integer">7327</score-value>
    <updated-at type="integer">1344256366</updated-at>
    <user-id type="integer">981</user-id>
  </MyScoreTable>
</data>
{
   "class_name":"MyScoreTable",
   "skip":0,
   "limit":100,
   "items":[
      {
         "_id":"5031e94c957fb3290b000002",
         "bonus_count":0.0,
         "created_at":1345448268,
         "expert_mode":false,
         "game_mode_name":"ds",
         "score_value":0,
         "updated_at":1350392824,
         "user_id":106,
         "_parent_id": null
      },
 	...
       ,
      {
         "_id":"501fb96e957fb3454f00073c",
         "game_mode_name":"ctf",
         "score_value":8247,
         "bonus_count":146.75,
         "expert_mode":true,
         "user_id":517,
         "_parent_id": null,
         "created_at":1344256366,
         "updated_at":1344256366
      }
   ]
}


Example request for records with score_value equal 1000

curl -X GET -d "score_value=1000" -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable

Example request for records with score_value less than 500

curl -X GET -d "score_value[lt]=500" -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable

Example request for records with score_value greater than 500 and less than or equal 100, with bonus_count equal 2.0

curl -X GET -d "score_value[gt]=500&score_value[lte]=1000&bonus_count=2.0" -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable

Example request for record by ID

curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable/501fb96e957fb3454f000732

Example request for record by IDs

curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable/501fb96e957fb3454f000732,501fb96e957fb3454f000733,501fb96e957fb3454f03434

Example request for records count

curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" -d "count=1" https://api.quickblox.com/data/MyScoreTable.json
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <count type="integer">1000</count>
</data>
{
   "class_name":"MyScoreTable",
   "skip":0,
   "limit":100,
   "items":{
      "count":1000
   }
}

Create new record

POST https://api.quickblox.com/data/<class_name>

To create new record you should use POST request with application/json or application/x-www-form-urlencoded content-type of POST-body. Received values will be casted according to data schema, defined in QuickBlox Admin Panel. Field, which present in data schema but not specified in POST-request will have null value.

Request

curl -X POST 
-H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" 
-d "expert_mode=true&game_mode_name=deathmatch&score_value=1024" 
https://api.quickblox.com/data/MyScoreTable
curl -X POST 
-H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" 
-d "expert_mode=true&game_mode_name=deathmatch&score_value=1024"
https://api.quickblox.com/data/MyScoreTable.json

Response

<?xml version="1.0" encoding="UTF-8"?>
<MyScoreTable>
  <_id>501fc714957fb3565700000b</_id>
  <_parent_id nil='true'/>
  <bonus-count nil="true"></bonus-count>
  <created-at type="integer">1344259860</created-at>
  <expert-mode type="boolean">true</expert-mode>
  <game-mode-name>deathmatch</game-mode-name>
  <score-value type="integer">1024</score-value>
  <updated-at type="integer">1344259860</updated-at>
  <user-id type="integer">106</user-id>
</MyScoreTable>
{
   "_id":"501fc747957fb3565700000d",
   "expert_mode":true,
   "game_mode_name":"deathmatch",
   "score_value":1024,
   "bonus_count":null,
   "user_id":106,
   "_parent_id": null,
   "created_at":1344259911,
   "updated_at":1344259911
}

Create multi records

POST https://api.quickblox.com/data/<class_name>/multi


The format of query

Parameter Applicable to types Usage example Description
record[<number_record>][{field_name}] Any type of field record[1][name]=Alex <number_record>
Numbering records in the query. Begin with 1 to N where N - your number last record.
{field_name}
Your field in Custom Object.


Request

curl -X POST -H "QB-Token: 281a7bc7c2984763ce77cda1b3641e551b93f887" -d "record[1][name]=Alex&record[1][age]=35&record[2][name]=Jon&record[2][age]=20&record[3][name]=Bill&record[3][age]=22" https://api.quickblox.com/data/MyTestUser/multi
curl -X POST -H "QB-Token: 281a7bc7c2984763ce77cda1b3641e551b93f887" -d "record[1][name]=Alex&record[1][age]=35&record[2][name]=Jon&record[2][age]=20&record[3][name]=Bill&record[3][age]=22" https://api.quickblox.com/data/MyTestUser/multi.json


Response

<?xml version="1.0" encoding="UTF-8"?>
<data type="array">
  <MyTestUser>
    <_id>522457b12195be5d8d3d01be</_id>
    <name>Alex</name>
    <age type="integer">35</age>
    <_parent-id nil="true"/>
    <user-id type="integer">2234</user-id>
    <created-at type="integer">1378113456</created-at>
    <updated-at type="integer">1378113456</updated-at>
  </MyTestUser>
  <MyTestUser>
    <_id>522457b12195be5d8d3d01c0</_id>
    <name>Bill</name>
    <age type="integer">22</age>
    <_parent-id nil="true"/>
    <user-id type="integer">2234</user-id>
    <created-at type="integer">1378113456</created-at>
    <updated-at type="integer">1378113456</updated-at>
  </MyTestUser>
  <MyTestUser>
    <_id>522457b12195be5d8d3d01bf</_id>
    <name>Jon</name>
    <age type="integer">20</age>
    <_parent-id nil="true"/>
    <user-id type="integer">2234</user-id>
    <created-at type="integer">1378113456</created-at>
    <updated-at type="integer">1378113456</updated-at>
  </MyTestUser>
</data>
{
    "class_name": "MyTestUser",
    "items": [
        {
            "_id": "522459222195be5d8d3d01c3",
            "name": "Bill",
            "age": 22,
            "_parent_id": null,
            "user_id": 2234,
            "created_at": 1378113826,
            "updated_at": 1378113826
        },
        {
            "_id": "522459222195be5d8d3d01c1",
            "name": "Alex",
            "age": 35,
            "_parent_id": null,
            "user_id": 2234,
            "created_at": 1378113826,
            "updated_at": 1378113826
        },
        {
            "_id": "522459222195be5d8d3d01c2",
            "name": "Jon",
            "age": 20,
            "_parent_id": null,
            "user_id": 2234,
            "created_at": 1378113826,
            "updated_at": 1378113826
        }
    ]
}

Update record by ID

PUT https://api.quickblox.com/data/<class_name>/<id>

To update existing record you should know record ID and use PUT request with application/json or application/x-www-form-urlencoded content-type of PUT(POST)-body. Received values will be casted according to data schema, defined in QuickBlox Admin Panel.

Special update operators

Operator Applicable to types Usage example Description
inc Integer, Float inc[field1]=1000 Increment field <field_name> to specified value. Value can positive or negative (i.e. decrement operation)
pull Arrays pull[field1]=val1 Removes specified value from array field
pull with filter Arrays pull[field1][ <filter_operator> ]=<filter_value> Removes all elements, which filtered by filter operator, from array
pull_all Arrays pull_all[field1][]=val1&pull_all[field1][]=val2 Removes all specified values from array
pop Arrays pop[field1]=1 Removes last element from array. To remove first element value should be equal -1
push Arrays push[field1][]=val1&push[field1][]=val2 Appends specified values to array
add_to_set Arrays add_to_set[<field_name>]=<values> Adds a value to an array only if the value is not in the array already
Update array element by index operator Arrays <field_name>[<index>]=val Update array element by index


Field, which present in data schema but not specified in PUT-request will have null value.
To nullify existing value you should specify "null" for application/x-www-/form-urlencoded, and null for application/json content-type.
Update request will update only specified fields (i.e. other fields will be left untouched).
For numeric fields (Integer&Float) exists special increment operator - inc, which increments or decrements numeric field.

Request

curl -X PUT -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" -d "expert_mode=false&score_value=240" https://api.quickblox.com/data/MyScoreTable/501fb96e957fb3454f000728
curl -X PUT -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" -d "expert_mode=false&score_value=240" https://api.quickblox.com/data/MyScoreTable/501fb96e957fb3454f000728.json

Response

<?xml version="1.0" encoding="UTF-8"?>
<MyScoreTable>
  <_id>501fb96e957fb3454f000728</_id>
  <_parent_id nil='true'/>
  <bonus-count type="float">63.5</bonus-count>
  <created-at type="integer">1344256366</created-at>
  <expert-mode type="boolean">false</expert-mode>
  <game-mode-name>ctf</game-mode-name>
  <score-value type="integer">240</score-value>
  <updated-at type="integer">1344341664</updated-at>
  <user-id type="integer">404</user-id>
</MyScoreTable>
{
   "_id":"501fb96e957fb3454f000728",
   "game_mode_name":"ctf",
   "score_value":240,
   "bonus_count":63.5,
   "expert_mode":false,
   "user_id":404,
   "_parent_id": null,
   "created_at":1344256366,
   "updated_at":1344342001
}


Example request for increment score_value by 100

curl -X PUT -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" -d "inc[score_value]=100" https://api.quickblox.com/data/MyScoreTable/501fb96e957fb3454f000728.json

Example request for decrement bonus_count by -2.5

curl -X PUT -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" -d "inc[bonus_count]=-2.5" https://api.quickblox.com/data/MyScoreTable/501fb96e957fb3454f000728.json

Update multi records

PUT https://api.quickblox.com/data/<class_name>/multi


The format of query

Parameter Applicable to types Usage example Description
record[<number_record>][id] String record[1][id]=522457b12195be5d8d3d01be id
ID of your record
record[<number_record>][{field_name}] Any type of field record[1][name]=Alex <number_record>
Numbering records in the query. Begin with 1 to N where N - your number last record.
{field_name}
Your field in Custom Object.


Request

curl -X PUT -H "QB-Token: 281a7bc7c2984763ce77cda1b3641e551b93f887" -d "record[1][id]=522457b12195be5d8d3d01bf&record[1][name]=Alex&record[1][age]=15&record[2][id]=522457b12195be5d8d3d01c0&record[2][name]=Bob" https://api.quickblox.com/data/MyTestUser/multi
curl -X PUT -H "QB-Token: 281a7bc7c2984763ce77cda1b3641e551b93f887" -d "record[1][id]=522457b12195be5d8d3d01bf&record[1][name]=Alex&record[1][age]=15&record[2][id]=522457b12195be5d8d3d01c0&record[2][name]=Bob" https://api.quickblox.com/data/MyTestUser/multi.json


Response

<?xml version="1.0" encoding="UTF-8"?>
<data type="array">
  <MyTestUser>
    <_id>522457b12195be5d8d3d01bf</_id>
    <_parent-id nil="true"/>
    <age type="integer">15</age>
    <created-at type="integer">1378113456</created-at>
    <name>Alex</name>
    <updated-at type="integer">1378118740</updated-at>
    <user-id type="integer">2234</user-id>
    <permissions>
      <read>
        <access>open</access>
      </read>
      <update>
        <access>owner</access>
      </update>
      <delete>
        <access>owner</access>
      </delete>
    </permissions>
  </MyTestUser>
  <MyTestUser>
    <_id>522457b12195be5d8d3d01c0</_id>
    <_parent-id nil="true"/>
    <age type="integer">22</age>
    <created-at type="integer">1378113456</created-at>
    <name>Bob</name>
    <updated-at type="integer">1378118740</updated-at>
    <user-id type="integer">2234</user-id>
    <permissions>
      <read>
        <access>open</access>
      </read>
      <update>
        <access>owner</access>
      </update>
      <delete>
        <access>owner</access>
      </delete>
    </permissions>
  </MyTestUser>
  <NotFound>
    <ids></ids>
  </NotFound>
</data>
{
    "class_name": "MyTestUser",
    "not_found": {
        "ids": []
    },
    "items": [
        {
            "_id": "522457b12195be5d8d3d01bf",
            "_parent_id": null,
            "age": 15,
            "created_at": 1378113456,
            "name": "Alex",
            "updated_at": 1378118876,
            "user_id": 2234,
            "permissions": {
                "read": {
                    "access": "open"
                },
                "update": {
                    "access": "owner"
                },
                "delete": {
                    "access": "owner"
                }
            }
        },
        {
            "_id": "522457b12195be5d8d3d01c0",
            "_parent_id": null,
            "age": 22,
            "created_at": 1378113456,
            "name": "Bob",
            "updated_at": 1378118876,
            "user_id": 2234,
            "permissions": {
                "read": {
                    "access": "open"
                },
                "update": {
                    "access": "owner"
                },
                "delete": {
                    "access": "owner"
                }
            }
        }
    ]
}

Delete records

by ID

DELETE https://api.quickblox.com/data/<class_name>/<id>

Request

curl -X DELETE -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable/501fb96e957fb3454f000728.json

Response

Empty body, HTTP 200 OK


by IDs

DELETE https://api.quickblox.com/data/<class_name>/<id1>,<id2>,<id3>

Request

curl -X DELETE -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable/501fb96e957fb3454f000728,501fb94e957fb3454f000728,501fb94e957fb3454f000722
curl -X DELETE -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/MyScoreTable/501fb96e957fb3454f000728,501fb94e957fb3454f000728,501fb94e957fb3454f000722.json

Response

<?xml version="1.0" encoding="UTF-8"?>
<data>
  <SuccessfullyDeleted>
    <ids>
      501fb96e957fb3454f000728
    <ids/>
  </SuccessfullyDeleted>
  <WrongPermissions>
    <ids>
      501fb94e957fb3454f000728
    </ids>
  </WrongPermissions>
  <NotFound>
    <ids>
      501fb94e957fb3454f000722
    </ids>
  </NotFound>
</data>
{
  "SuccessfullyDeleted": {
    "ids": [
      "501fb96e957fb3454f000728"
    ]
  },
  "WrongPermissions": {
    "ids": [
      "501fb94e957fb3454f000728"
    ]
  },
  "NotFound": {
    "ids": [
      "501fb94e957fb3454f000722"
    ]
  }
}




Relations

Create relation

To create a relation between records of two different classes you can send a POST request to the

https://api.quickblox.com/data/<parent_class_name>/<record_id>/<child_class_name>

For example, we have the class "Movie" containing the record with fields "Title", "Year", "Duration" "Genre".

The record described above could look like this:

<?xml version="1.0" encoding="UTF-8"?>
<Movie>
  <Duration type='integer'>143</Duration>
  <Genre> Action | Adventure | Crime</Genre>
  <Title>Skyfall</Title>
  <Year type='integer'>2012</Year>
  <_id>50aa4d8fefa357fa14000001</_id>
  <_parent_id nil='true'/>
  <created-at type='integer'>1353338255</created-at>
  <updated-at type='integer'>1353338255</updated-at>
  <user-id type='integer'>2335</user-id>
</Movie>
{
   "_id":"50aa4d8fefa357fa14000001",
   "Title":"Skyfall",
   "Year":2012,
   "Duration":143,
   "Genre":"Action | Adventure | Crime",
   "user_id":2335,
   "_parent_id": null,
   "created_at":1353338255,
   "updated_at":1353338255
}

Also we have the class "Rating" that contains fields "Score", "Review", "Comment". So we can create a record for it that will point to the record of the class "Movies" like so:

curl -X POST -H "QB-Token: 8e9ce6c86ec971349d585b83022ee6312850d9bb" -d "Score=8&Comment=This is one of the best Bond movies I have ever seen&Review=The story is superbly put together and has some interesting twists, the action is well done and contains none of the shaky cam which plagued the last film. The actors all do a great job. Some might still be put off by Daniel Craig's rough version of Bond, but I like it and he even has a few good old fashioned one-liners here." https://api.quickblox.com/data/Movie/50aa4d8fefa357fa14000001/Rating

The response body contains all the user-provided fields, plus the _id, _parent_id, created-at, updated-at and user_id fields:

<?xml version="1.0" encoding="UTF-8"?>
<Rating>
  <Comment>This is one of the best Bond movies I have ever seen</Comment>
  <Review> The story is superbly put together and has some interesting twists, the action is well done and contains none of the shaky cam which plagued the last film. The actors all do a great job. Some might still be put off by Daniel Craig's rough version of Bond, but I like it and he even has a few good old fashioned one-liners here.</Review>
  <Score type='integer'> 8 </Score>
  <_id>50aa53adefa357f714000003</_id>
  <_parent_id> 50aa4d8fefa357fa14000001</_parent_id>
  <created-at type='integer'>1353339821</created-at>
  <updated-at type='integer'>1353339821</updated-at>
  <user-id type='integer'>2700</user-id>
</Rating>
{
   "_id":"50aa6372efa357fa14000005",
   "Score":8,
   "Comment":"This is one of the best Bond movies I have ever seen",
   "Review":"The story is superbly put together and has some interesting twists, the action is well done and contains none of the shaky cam which plagued the last film. The actors all do a great job. Some might still be put off by Daniel Craig's rough version of Bond, but I like it and he even has a few good old fashioned one-liners here.",
   "_parent_id":"50aa4d8fefa357fa14000001",
   "user_id":2700,
   "created_at":1353343858,
   "updated_at":1353343858
}

You can also to do this by sending a POST request to the class URL with _parent_id as URL-encoded parameter like so:

curl -X POST -H "QB-Token: 8e9ce6c86ec971349d585b83022ee6312850d9bb" -d "_parent_id=50aa4d8fefa357fa14000001&..." https://api.quickblox.com/data/Rating

Get related records

For retrieving a record that has pointer to parent record you can send a GET request to

https://api.quickblox.com/data/<parent_class_name>/<record_id>/<child_class_name>

For example, to retrieve the record we created above:

curl -X GET -H "QB-Token: 8e9ce6c86ec971349d585b83022ee6312850d9bb" https://api.quickblox.com/data/Movie/50aa4d8fefa357fa14000001/Ratings

The response body contains all records that are related to specified parent's record:

<?xml version="1.0" encoding="UTF-8"?>
<data type='array'>
  <Rating>
    <Comment nil='true'/>
    <Review nil='true'/>
    <Score nil='true'/>
    <_id>50aa4e31efa357f414000007</_id>
    <_parent_id> 50aa4d8fefa357fa14000001</_parent_id>
    <created-at type='integer'>1353338417</created-at>
    <updated-at type='integer'>1353338417</updated-at>
    <user-id type='integer'>2700</user-id>
  </Rating>
  <Rating>
    <Comment> This is one of the best Bond movies I have ever seen </Comment>
    <Review> The story is superbly put together and has some interesting twists, the action is well done and contains none of the shaky cam which plagued the last film. The actors all do a great job. Some might still be put off by Daniel Craig's rough version of Bond, but I like it and he even has a few good old fashioned one-liners here. </Review>
    <Score type='integer'>8</Score>
    <_id> 50aa53adefa357f714000003</_id>
    <_parent_id>50aa4d8fefa357fa14000001</_parent_id>
    <created-at type='integer'>1353339821</created-at>
    <updated-at type='integer'>1353339821</updated-at>
    <user-id type='integer'>2700</user-id>
  </Rating>
</data>
{
   "class_name":"Ratings",
   "skip":0,
   "limit":100,
   "items":[
      {
         "_id":"50aa4e31efa357f414000007",
         "_parent_id":"50aa4d8fefa357fa14000001",
         "Score":null,
         "Comment":null,
         "Review":null,
         "user_id":2700,
         "created_at":1353338417,
         "updated_at":1353338417
      },
      {
         "_id":"50aa53adefa357f714000003",
         "Score":8,
         "Comment":"This is one of the best Bond movies I have ever seen",
         "Review":"The story is superbly put together and has some interesting twists, the action is well done and contains none of the shaky cam which plagued the last film. The actors all do a great job. Some might still be put off by Daniel Craig's rough version of Bond, but I like it and he even has a few good old fashioned one-liners here.",
         "_parent_id":"50aa4d8fefa357fa14000001",
         "user_id":2700,
         "created_at":1353339821,
         "updated_at":1353339821
      }
   ]
}


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

In the QuickBlox user can add the Access Control list only in the Custom objects module.

Permission scheme

QuickBlox Permission scheme contains five permissions levels:

  • Open
    Such permission schema means that any user within application can access to record/records in the class and is allowed to perform action with the current permission level
  • Owner
    Owner permission level means that only Owner (user who created a record) is allowed to perform action with the current permission level
  • Not allowed
    No one (except the Account Administrator) can make the chosen action
  • Open for groups
    Users which have a specified tag / tags (see more info about how to set tags for user in Users module API) will be included in the group which is allowed to perform action with the current permission level. A current permission level can consist of one or several groups (number of groups is not limited). Tags can be added / deleted in the user’s profile.
  • Open for users ids
    Only users that are specified in the permission level can make a required action with a record. One or several users can be specified (number of users isn’t limited)

Actions available for the entity

  • Create
    Creation a record
  • Read
    Retrieving and reading the info about the chosen record
  • Update
    Updating any parameter for the chosen record (only those parameters that can be set by the user can be updated)
  • Delete
    Deleting a record

Permission levels

There are two levels of access which QuickBlox is provided in such Permissions scheme: Class and Record.

Class entity

Class is an entity that contains records. Only the Account Administrator (web panel) can create a class in the Custom object module and make all possible actions with it. Operations with Class entity are not allowed in API

All actions (Create, Read, Update and Delete) are available for the ‘Class’ entity and are applicable for all records in the class. Every action has the separate permission level available. The exception is a Create action that isn’t available for Owner permission level.

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

Edit-permission-button.png

Default Class permission schema is using while creating a class:

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

You should mark checkboxes to enable Class permissions

Record entity

Record is an entity within the Class in the Custom Objects module that has it’s own permission levels. Creation of the record is available in the Web panel and in API (see Create a record request). All permission levels except the Not allowed are available for the record and there are only three actions are available and applicable for the record: Read, Update and Delete.

Default Record permission scheme is using while creating a class:

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

To set a permission levels open the required Class and click on the record to open it to change.

Set-permissions-on-record.png

Choosing a permission schema

In the same time only ONE permission level can be applicable to the record: Сlass permission schema or Record permission schema. To apply the Class permission levels to ALL records in the class tick the checkbox ‘Use Class permissions’ near the required Action in the Admin panel.

Class-permissions-scheme.png

Note: Using the Class permission schema means that Record permission schema won’t be affected on reсord.

In case when the Admin doesn’t tick the checkbox in the Admin panel user has a possibility to change the permission levels for every separate record in the table or create a new one with the ACL that user requires

Create new record with permissions

To create a record with the permissions you should add a parameter permissions[action_name][access] as a new field to 'Create a record request

Permission Syntax Example
  • Open
  • Owner
permissions[action_name][access] permissions[read][access]=open
Open for users IDs

permissions[action_name][access]=open_for_users_ids

permissions[action_name][ids]=id_1,id_2,id_3,...

permissions[update][access]=open_for_users_ids

permissions[update][ids]=3,12

Open for groups

permissions[action_name][access]=open_for_groups

permissions[action_name][groups]=group_name_1,group_name_2

permissions[delete][access]=open_for_groups

permissions[delete][groups]=experience,rate


Request

curl -X POST -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" -d "expert_mode=true&game_mode_name=bestgame&score_value=777&permissions[read][access]=owner&permissions[update][access]=open_for_groups&permissions[update][groups]=world"
https://api.quickblox.com/data/MyScoreTable
curl -X POST -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" -d "expert_mode=true&game_mode_name=bestgame&score_value=777&permissions[read][access]=owner&permissions[update][access]=open_for_groups&permissions[update][groups]=world"
https://api.quickblox.com/data/MyScoreTable.json

Response

<?xml version="1.0" encoding="UTF-8"?>
<MyScoreTable>
  <_id>51caf7fcefa35760d1000018</_id>
  <_parent_id nil='true'/>
  <expert-mode type='boolean'>true</expert-mode>
  <game-mode-name>bestgame</game-mode-name>
  <score-value type='integer'>777</score-value>
  <bonus-count nil='true'/>
  <user-id type='integer'>1315</user-id>
  <created-at type='integer'>1372256252</created-at>
  <updated-at type='integer'>1372256252</updated-at>
  <permissions>
    <read>
      <access>owner</access>
    </read>
    <update>
      <access>open_for_groups</access>
      <users-groups type='array'>
        <users-group>world</users-group>
      </users-groups>
    </update>
    <delete>
      <access>owner</access>
    </delete>
  </permissions>
</MyScoreTable>
{
  "_id": "51cafcd6efa3573c3e000013",
  "_parent_id": null,
  "expert_mode": true,
  "game_mode_name": "bestgame",
  "score_value": 777,
  "bonus_count": null,
  "user_id": 1315,
  "created_at": 1372257494,
  "updated_at": 1372257494,
  "permissions": {
    "read": {
      "access": "owner"
    },
    "update": {
      "access": "open_for_groups",
      "users_groups": [
        "world"
      ]
    },
    "delete": {
      "access": "owner"
    }
  }
}


Update record with permissions

To update an existing record use the permissions[action_name][access] parameter in the PUT request. All data that are specified incorrectly or were not specified at all are ignoring

Request

curl -X PUT -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" -d “permissions[read][access]=open_for_groups&permissions[read][groups]=world,man” 
https://api.quickblox.com/data/MyScoreTable/51caa06eefa357d26c00000d
curl -X PUT -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" -d “permissions[update][access]=owner” 
http://api.quickblox.com/data/MyScoreTable/51d28377efa357ba9a000005.json

Response

<?xml version="1.0" encoding="UTF-8"?>
<MyScoreTable>
  <_id>51d28377efa357ba9a000005</_id>
  <_parent_id/>
  <expert-mode type='boolean'>true</expert-mode>
  <game-mode-name>MyGame</game-mode-name>
  <score-value type='integer'>456</score-value>
  <user-id type='integer'>2</user-id>
  <created-at type='integer'>1372750711</created-at>
  <updated-at type='integer'>1372750920</updated-at>
  <permissions>
    <read>
      <access>open_for_groups</access>
      <users-groups type='array'>
        <users-group>world</users-group>
        <users-group>man</users-group>
      </users-groups>
    </read>
    <update>
      <access>open</access>
    </update>
    <delete>
      <access>owner</access>
    </delete>
  </permissions>
</MyScoreTable>
{
  "_id": "51d28377efa357ba9a000005",
  "_parent_id": "",
  "expert_mode": true,
  "game_mode_name": "MyGame",
  "score_value": 456,
  "user_id": 2,
  "created_at": 1372750711,
  "updated_at": 1372751112,
  "permissions": {
    "read": {
      "access": "open_for_groups",
      "users_groups": [
        "world",
        "man"
      ]
    },
    "update": {
      "access": "owner"
    },
    "delete": {
      "access": "owner"
    }
  }
}


Retrieve record by ID to view it’s 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 a possibility to view a record’s permissions

Request

curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" -dpermissions=1” https://api.quickblox.com/data/MyScoreTable/51d28377efa357ba9a000005
curl -X GET -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" -dpermissions=1” https://api.quickblox.com/data/MyScoreTable/51d28377efa357ba9a000005.json

Response

<?xml version="1.0" encoding="UTF-8"?>
<permissions>
  <read>
    <access>open</access>
  </read>
  <update>
    <access>owner</access>
  </update>
  <delete>
    <access>owner</access>
  </delete>
  <record-id>51d28377efa357ba9a000005</record-id>
</permissions>
{
  "permissions": {
    "read": {
      "access": "open"
    },
    "update": {
      "access": "owner"
    },
    "delete": {
      "access": "owner"
    },
    "record_id": "51dd06ceefa357b69d000021"
  }
}


Files

‘File’ field type is created for easily working with content from Custom Objects module. There is an ability to upload, download, update and delete content of file fields.

The max file size is 32 MB.

Upload/Update file

Request

curl -X POST -H "QB-Token: e7cde5f7f5b93f3fa5ac72a281777cbf0f908374" -F "field_name=avatar" -F 'file=@"ava.jpg"' https://api.quickblox.com/data/<Class_name>/<record_id>/file
curl -X POST -H "QB-Token: e7cde5f7f5b93f3fa5ac72a281777cbf0f908374" -F "field_name=avatar" -F 'file=@"ava.jpg"' https://api.quickblox.com/data/<Class_name>/<record_id>/file.json

Response

<avatar>
<_id>52381576efa357e8ea000004</_id>
<file-id>52381576efa357e8ea000002</file-id>
<size type="integer">2115233</size>
<name>IMG_20130916_154600.jpg</name>
<content-type>image/jpeg</content-type>
</avatar>
{"_id":"52382762efa357b62d000008","file_id":"52382761efa357b62d000006","size":3045266,"name":"IMG_20130916_162318.jpg","content_type":"image/jpeg"}


Download file

Request

curl -X GET -H "QB-Token: 53247fce22672e627880bf9a7060aadecc2c3e59" -d"field_name=avatar" https://api.quickblox.com/data/<Class_name>/<record_id>/file
curl -X GET -H "QB-Token: 53247fce22672e627880bf9a7060aadecc2c3e59" -d"field_name=avatar" https://api.quickblox.com/data/<Class_name>/<record_id>/file.json

Delete file

Request

curl -X DELETE -H "QB-Token: e7cde5f7f5b93f3fa5ac72a281777cbf0f908374" -d"field_name=avatar" https://api.quickblox.com/data/<Class_name>/<record_id>/file
curl -X DELETE -H "QB-Token: e7cde5f7f5b93f3fa5ac72a281777cbf0f908374" -d"field_name=avatar" https://api.quickblox.com/data/<Class_name>/<record_id>/file.json

Response

Empty body, status: 200
Empty body, status: 200


Tips and Tricks

Sort by _id

According to Module description , _id field contains info about creation timestamp. It means that sorting on an _id field is roughly equivalent to sorting by created_at field, but works much faster because _id field has predefined index.

It is highly recommended to use sort by _id field instead of sort by created_at field:

curl -X GET -d "sort_desc=_id&limit=10" -H "QB-Token: 4d617908bf432bd0a72e2e089ed500e76a2c1a3b" https://api.quickblox.com/data/Message

Skip parameter performance

The skip parameter is often expensive because it requires the server to walk from the beginning of the collection to get the offset or skip position before beginning to return result. As offset increases, skip will become slower and more CPU intensive. With larger collections, skip may become IO bound.

Instead of using big value of skip try to improve your query. Maybe you don't need it.