API Introduction
Request format
For POST and PUT requests, the request body must be JSON, with the Content-Type header set to application/json.
Authentication is done via HTTP headers.
The X-Tiggzi-Database-Id header identifies which database you are accessing. The database id can be found in the Dashboard tab for the database. This header is always required.
The X-Tiggzi-Session-Token header identifies the user session.
Tiggzi Database supports CORS (Cross-origin resource sharing) so you it’s very easy to use from JavaScript (it doesn’t require using JSONP or proxies).
Response Format
The response format for all requests is a JSON object.
An HTTP status code indicates whether the request succeeded or not.
A 2xx status code indicates success.
A 4xx status code indicates failure.
When a request fails, the response body is still JSON, but will contain an error message. For example,
{"code": xxx,"error": "error message"}
Object API
Object Format
Tiggzi Database stores data in JSON format (it’s running MongoDB). For example, if we are building a ToDo app, an task object might look like this:
{
"priority": "High",
"taskName": "Use cool API"
}
When a new object is created, the following three columns are automatically created: _createdAt, _updatedAt, and _id. These field names are reserved, so you cannot set them yourself. Using the object above, if we did a GET on it, it would look like this, including the reserved fields.
{
"_createdAt": "2012-07-10T20:45:50.017Z",
"_updatedAt": "2012-07-10T20:45:57.078Z",
"_id": "4ffcf6eee4b0211629c4ad03",
"priority": "High",
"taskName": "Use cool API"
}
If the collection name is todo, then the URL to the collection would be:
https://api.tiggzi.com/rest/1/db/collections/todo
if we want to work with a particular object (from above for example), then the URL would be this:
https://api.tiggzi.com/rest/1/db/collections/todo/[object_id]
or
https://api.tiggzi.com/rest/1/db/collections/ToDo/4ffcf6eee4b0211629c4ad03
To make it very easy to work with collections and objects, you can get the almost complete curl command (need to enter collection name) for each REST verb in the Browser collection:
Click on any of the REST verbs (GET, FIND, CREATE, UPDATE, DELETE) to get the curl request.
Creating Objects
To create a new object, send a POST request. For example:
curl -X POST
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-H "Content-Type: application/json"
-d "{"taskName":"Build an app", "priority":"High"}"
https://api.tiggzi.com/rest/1/db/collections/todo
If everything goes well, the JSON response should look like this:
{
"_id":"4ffcfd9fe4b0211629c4ad06",
"_createdAt":"2012-07-10T21:14:23.637Z"
}
_id is the auto-generated id for the new object and _createdAt is the time when the object was created.
Retrieving All Objects
To get all the objects from a collection, issue a GET request:
curl -X GET -H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" https://api.tiggzi.com/rest/1/db/collections/todo
The response body is a JSON object containing all the user-provided fields plus the _createdAt, _updatedAt, and _id fields:
[
{
"_updatedAt": "2012-07-10T20:45:57.078Z",
"priority": "High",
"taskName": "Use cool API",
"_id": "4ffcf6eee4b0211629c4ad03",
"_createdAt": "2012-07-10T20:45:50.017Z"
},
{
"priority": "High",
"_updatedAt": "2012-07-10T21:12:08.937Z",
"taskName": "Build an app",
"_id": "4ffcfd18e4b0211629c4ad04",
"_createdAt": "2012-07-10T21:12:08.937Z"
},
{
"priority": "Low",
"_updatedAt": "2012-07-10T21:13:40.054Z",
"taskName": "Go shopping",
"_id": "4ffcfd74e4b0211629c4ad05",
"_createdAt": "2012-07-10T21:13:40.054Z"
}
]
Retrieve a specific object
To get a specific object, issue a GET command as above but also add the object id to the end of the URL. For example:
curl -X GET -H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" https://api.tiggzi.com/rest/1/db/collections/todo/4ffcf6eee4b0211629c4ad03
The result would be the following JSON:
{
"priority": "High",
"taskName": "Use cool API",
"_createdAt": "2012-07-10T20:45:50.017Z",
"_id": "4ffcf6eee4b0211629c4ad03",
"_updatedAt": "2012-07-10T20:45:57.078Z"
}
Updating Objects
To update or change an object, send a PUT request. For example:
curl -X PUT
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-H "Content-Type: application/json"
-d "{"priority":"High"}"
https://api.tiggzi.com/rest/1/db/collections/todo/4ffcf6eee4b0211629c4ad03
We changed the priority of the object from High to Low. As we are changing a particular object, the object id has to be used in the URL.
The result is JSON containing the time when the object was upated.
{
"_updatedAt": "2012-07-10T21:30:11.153Z"
}
Updating Arrays
To help with storing array data, there are three operations that can be used to atomically change an array field:
- Add appends the given array of objects to the end of an array field.
- AddUnique adds only the given objects which aren’t already contained in an array field to that field. The position of the insert is not guaranteed.
- Remove removes all instances of each given object from an array field.
Each method takes an array of objects to add or remove in the “objects” key. For example, we can add items to the set-like “skills” field like so:
curl -X PUT \
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-H "Content-Type: application/json" \
-d '{"checklist":{"__op":"AddUnique","objects":["add header","add footer"]}}' \
https://api.tiggzi.com/rest/1/db/collections/todo/4ffcf6eee4b0211629c4ad03
Deleting Objects
To delete an object, send a DELETE request with the object id in the URL. For example:
curl -X DELETE -H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" https://api.tiggzi.com/rest/1/db/collections/todo/4ffcf6eee4b0211629c4ad03
Data Types
Date
The Date type value is a string which contains a UTC timestamp stored in ISO 8601 format with millisecond precision: YYYY-MM-DDTHH:MM:SS.MMMZ.
Array
Array value is a list of primitive values, such as: string, number or boolean. You need to separate the values with comma and surround it with brackets:
curl -X POST
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-H "Content-Type: application/json" \
-d '{"checklist": ["add button", "add link"]}' \
https://api.tiggzi.com/rest/1/db/collections/todo/
Pointer
The Pointer type is used when we need to set object link as the value of another object. It contains the collection name and _id of the referred-to value. To set the value you need to pass an object just like this:
curl -X POST
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-H "Content-Type: application/json" \
-d '{"subtask": {"collName":"todo", "_id":"4ffcf6eee4b0211629c4ad03"}}' \
https://api.tiggzi.com/rest/1/db/collections/todo/
Queries
Basic Queries
You can retrieve multiple objects at once by sending a GET request to the collection URL. Without any URL parameters, this simply lists objects in the collection:
curl -X GET -H "X-Tiggzi-Database-Id: Jqh5I4hekNHe1yuDOr6p1ys....." https://api.tiggzi.com/rest/1/db/collections/todo
The result would be in JSON format that contains all the objects in this collection:
[
{
"taskName": "Build an app",
"_updatedAt": "2012-07-12T06:15:22.662Z",
"_id": "4ffecde0e4b0452929274b56",
"_createdAt": "2012-07-12T06:15:12.092Z",
"priority": "High"
},
{
"taskName": "Buy groceries",
"_updatedAt": "2012-07-12T06:15:34.830Z",
"_id": "4ffecdf4e4b0452929274b57",
"_createdAt": "2012-07-12T06:15:32.526Z",
"priority": "High"
},
{
"taskName": "Check email",
"_updatedAt": "2012-07-12T06:15:54.416Z",
"_id": "4ffece07e4b0452929274b58",
"_createdAt": "2012-07-12T06:15:51.858Z",
"priority": "Low"
}
]
Query Constraints
It’s also possible to specify a where clause in the request. The value of where parameter need to be in JSON format. As we are sending a GET request, the JSON value then is also URL encoded. Using the example JSON above, let’s say we only want to get all tasks with High priority.
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G --data-urlencode 'where={"priority": "High"}'
https://api.tiggzi.com/rest/1/db/collections/todo
The resulting JSON will look like this:
[
{
"_updatedAt": "2012-07-12T06:15:22.662Z",
"_createdAt": "2012-07-12T06:15:12.092Z",
"_id": "4ffecde0e4b0452929274b56",
"taskName": "Build an app",
"priority": "High"
},
{
"_updatedAt": "2012-07-12T06:15:34.830Z",
"_createdAt": "2012-07-12T06:15:32.526Z",
"_id": "4ffecdf4e4b0452929274b57",
"taskName": "Buy groceries",
"priority": "High"
}
]
The where parameter also supports the following comparison values:
| $lt | Less Than |
| $lte | Less Than Or Equal To |
| $gt | Greater Than |
| $gte | Greater Than Or Equal To |
| $ne | Not Equal To |
| $in | Contained In |
| $nin | Not Contained in |
| $exists | A value is set for the key |
The following examples will use this JSON data (note that _id, _createAt, _updatedAt were removed from results):
[
{
"studentId": 10,
"studentName": "John"
},
{
"studentId": 20,
"studentName": "Donna"
},
{
"studentId": 30,
"studentName": "Sasha"
},
{
"studentId": 40,
"studentName": "Priscila"
},
{
"studentId": 50,
"studentName": "Dan"
},
{
"studentId": 60,
"studentName": "Sarah"
},
{
"studentId": 70,
"studentName": "Olga"
},
{
"studentId": 80,
"studentName": "Anna"
},
{
"studentId": 90,
"studentName": "Jacob"
},
{
"studentId": 100,
"studentName": "Dina"
}
]
Less Than ($lt)
Let’s say we want to get only students where the student id is less than 50 ($lt):
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G --data-urlencode 'where={"studentId": {"$lt": 50}}'
https://api.tiggzi.com/1/db/collections/students
The result is only students with student id of 10, 20, 30, and 40.
Less Then Or Equal To ($lte)
Let’s say we want to get only students where the student id is less then or equal to 50 ($lte):
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G --data-urlencode 'where={"studentId": {"$lte": 50}}'
https://api.tiggzi.com/1/db/collections/students
The result would as above, but will now also include 50.
Greater Than ($gt)
Going the opposite way, if we want to show all student with student id of 50 or higher ($gt):
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G --data-urlencode 'where={"studentId": {"$gt": 50}}'
https://api.tiggzi.com/1/db/collections/student
Would return objects with id’s of 60, 70, 80, 90, and 100.
Greater Than Or Equal To ($gte)
Using greater than or equal ($gte) is very similar:
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G --data-urlencode 'where={"studentId": {"$gte": 50}}'
https://api.tiggzi.com/1/db/collections/students
Not Equal To ($ne)
Using not equal to ($ne), we can specify which object we don’t want to select:
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G --data-urlencode 'where={"studentId": {"$ne": 20}}'
https://api.tiggzi.com/1/db/collections/students
We will get all student objects except the student with id of 20.
Included In ($in)
To get particular objects, we can use contained in ($in):
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G --data-urlencode 'where={"studentId": {"$in": [20,80]}}'
https://api.tiggzi.com/1/db/collections/students
Would return only student objects with id’s of 20 and 80
Not Included In ($nin)
The opposite of contained in ($in) is not contained in ($nin):
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G --data-urlencode 'where={"studentId": {"$nin": [20,80]}}'
https://api.tiggzi.com/1/db/collections/students
Would return all objects besides objects with id’s of 20 and 80.
A Value is Set ($exists)
The last option is to text whether a value is set for a column using $exists
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G --data-urlencode 'where={"studentId": {"$exists":true}}'
https://api.tiggzi.com/1/db/collections/students
As every object has the id set, above query would return the entire list. Or, specifying false:
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G --data-urlencode 'where={"studentId": {"$exists":false}}'
https://api.tiggzi.com/1/db/collections/students
would return an empty list as every object has the student id set.
Sorting
To sort data, specify sort as request parameter and then the column by which you want to sort. For example, sorting by studentName column, in ascending order:
curl -X GET -H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" -G --data-urlencode 'sort=studentName' https://api.tiggzi.com/1/db/collections/students
To sort in descending order, specify the column name with - before it:
curl -X GET -H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" -G --data-urlencode 'sort=-studentName' https://api.tiggzi.com/1/db/collections/students
You can also sort by more than one column:
curl -X GET -H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" -G --data-urlencode 'sort=studentName,studentId' https://api.tiggzi.com/1/db/collections/students
Pagination
To limit the number of objects you get, use the limit parameter. The following query will return the first 5 objects:
curl -X GET -H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" -G --data-urlencode 'limit=5' https://api.tiggzi.com/1/db/collections/students
In addition to how many objects to return, you can also specify from which object count to start with skip parameter. The following will start at object 6 (skip the first 5) and return (limit) 5 objects.
curl -X GET -H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" -G --data-urlencode 'limit=5' --data-urlencode 'skip=5' https://api.tiggzi.com/1/db/collections/students
Queries on Array Values
For keys with an array type, you can find objects where the key’s array value contains 2 by:
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G
--data-urlencode 'where={"arrayKey": 2}'
https://api.tiggzi.com/rest/1/db/collections/SomeOtherObject
Queries on Pointer Values
To properly get an object with specific pointer value you should provide an object with exactly the same fields in where parameter:
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G
--data-urlencode 'where={"subtask": {"collName":"todo", "_id":"8uiocdf8e4b0452929274b57"}}'
https://api.tiggzi.com/rest/1/db/collections/todo/
In some situations, you want to return multiple types of related objects in one query. You can do this by passing the field to include in the include parameter:
curl -X GET \
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-G \
--data-urlencode 'include=subtask' \
https://api.tiggzi.com/rest/1/db/collections/todo
When the query is issued with an include parameter for the key holding this pointer, the pointer will be expanded to the object:
{
"_id": "4ffcfd9fe4b0211629c4ad06",
"createdAt": "2011-12-06T20:59:34.428Z",
"updatedAt": "2011-12-06T20:59:34.428Z",
"otherFields": "willBeIncluded"
}
You can also do multi level includes using dot notation:curl -X GET \
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-G \
--data-urlencode 'include=subtask.subtask' \
https://api.tiggzi.com/rest/1/db/collections/todo
You can also issue a query with multiple fields included by passing a comma-separated list of keys as the include parameter:curl -X GET \
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-G \
--data-urlencode 'include=subtask,reminder' \
https://api.tiggzi.com/rest/1/db/collections/todoQueries on String Values
You can use regular expressions to search over values containing strings. The constraint is represented by a hash with the key $regex mapping to a regular expression. For example:
curl -X GET
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01"
-G --data-urlencode 'where={"studentName": "$regex": "^A"}}'
https://api.tiggzi.com/1/db/collections/students
Counting Objects
If you want to count how many objects there are in a collection, send the following request:
curl -X GET -H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" -G --data-urlencode 'count=1' https://api.tiggzi.com/rest/1/db/collections/todo
The result will be:
[
{
"count": 3
}
]
File API
File API allows uploading and download of files. The following API is available:
Note that all File API requires sending X-Tiggzi-Session-Token header. You can get its value when a user is signed in. This is to prevent any one but the user uploading any number of files.
Uploading Files
curl -X POST -H "Content-Type: [set_to_file_type]" -H "X-Tiggzi-Database-Id: 498ad4r0e4b9348a121cf6ea" -H "X-Tiggzi-Session-Token: 900ad7b0e4b9808a456cf5ba" https://api.tiggzi.com/rest/1/db/files/[fileName]
For example, if the file name you want to upload is ABC.jpg, the URL will be:
https://api.tiggzi.com/rest/1/db/files/ABC.jpg
The JSON response will look like this. The actual file name is pre-pended with a random id to make the names unique. This is the actual file name under which the file is stored in the database:
{"filename":"cc30aa08-3d30-4236-a2fc-8c7a768d02c6.ABC.jpg", fileurl: 'https://api.tiggzi.com/rest/1/db/files/cc30aa08-3d30-4236-a2fc-8c7a768d02c6.ABC.jpg'}
Retrieving Files
curl -X GET -H "Content-Type: [set_to_file_type]" -H "X-Tiggzi-Database-Id: 498ad4r0e4b9348a121cf6ea" -H "X-Tiggzi-Session-Token: 900ad7b0e4b9808a456cf5ba" https://api.tiggzi.com/rest/1/db/files/[fileName]
Deleting Files
curl -X DELETE -H "Content-Type: [set_to_file_type]" -H "X-Tiggzi-Database-Id: 498ad4r0e4b9348a121cf6ea" -H "X-Tiggzi-Session-Token: 900ad7b0e4b9808a456cf5ba" https://api.tiggzi.com/rest/1/db/files/[fileName]
When a file is succussfuly deleted, the JSON response will be:
{
"status": "success",
"result": "deleted"
}
Users
Introduction
Many mobile apps have the notion of a User, where each user may sign up for an account in the app, view his or her information, perform actions and change his or her password. As this functionality is very common, Tiggzi Database comes with a built in User Management feature. Users are created in a built-in collection User and are managed via Users tab in the console for databases.
A User object is very similar to any other object you create with one exception that the User object has required username and password fields. The password field is stored encrypted in the database and will not be shown shown in any client request.
Signing up
To sign up (create) a new user, send a POST request that includes the username and password parameters (in JSON format):
curl -X POST \
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-H "Content-Type: application/json" \
-d "{"username":"user_name","password":"user_password"}" \
https://api.tiggzi.com/rest/1/db/users
On succesful create the JSON response will look like this:
{
"_updatedAt": "2012-07-13T16:20:37.580Z",
"_createdAt": "2012-07-13T16:20:37.580Z",
"_id": "5000ad45e4b0452929274b9a",
"username": "Anna",
"password": ""
}curl -X POST \ -H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \ -H "Content-Type: application/json" \
-d "{"username":"user_name","password":"user_password", "email":"user_email"}" \
https://api.tiggzi.com/rest/1/db/usersSigning in (login)
Once a user has been created via signing up, to sign in (login), issue the following request:
curl -X GET \
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-G --data-urlencode 'username=[user_name]' --data-urlencode 'password=[user_password]' \
https://api.tiggzi.com/rest/1/db/login
JSON response will look like this:
{
"_id": "50047c7de4b0452929274bb8",
"sessionToken": "80aeb50a-14de-4fd2-9c8e-11c5b60d8959"
}
Save the sessionToken if you need to access the user information in subsequent requests. You can save the token in local storage.
Getting particular user details
To retrieve a particular user, issue a GET request with the user id in the URL and also adding the X-Tiggzi-Session-Token header for authentication. The session token is returned by doing a login.
curl -X GET \
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-H "X-Tiggzi-Session-Token: 80aeb50a-14de-4fd2-9c8e-11c5b60d8959" \
https://api.tiggzi.com/rest/1/db/users/5000ad45e4b0452929274b9aThe response will look like this:
{
"_updatedAt": "2012-07-16T13:41:33.489Z",
"password": "",
"_id": "50047c7de4b0452929274bb8",
"username": "max",
"email": "[email protected]",
"_createdAt": "2012-07-16T13:41:33.489Z"
}
If the User object has any additional fields (columns), you will get them back as well.
Getting all the users
You can retrieve multiple users at once by sending a GET request to the root users URL. Without any URL parameters, this simply lists users:
curl -X GET \
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-H "X-Tiggzi-Session-Token: 80aeb50a-14de-4fd2-9c8e-11c5b60d8959" \
https://api.tiggzi.com/rest/1/db/usersThe return JSON will include a list of all the users.
You may also apply any of the queries options.
Updating users
To update an existing user, send a PUT request specifying the fields you want to update. Any fields not included in the request will not be updated. Here is an example updating the email for user ‘joe’. You need to specify the X-Tiggzi-Session-Token for authentication as well as user id in the URL.
curl -X PUT \
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-H "X-Tiggzi-Session-Token: 80aeb50a-14de-4fd2-9c8e-11c5b60d8959" \
-d "{"email":"[email protected]"}" \
https://api.tiggzi.com/rest/1/db/users/50048dc9e4b0452929274bc1
The response will contain the updated User object:
{
"email": "[email protected]",
"_createdAt": "2012-07-16T14:55:21.697Z",
"password": "",
"_updatedAt": "2012-07-16T14:58:08.073Z",
"_id": "50048dc9e4b0452929274bc1",
"username": "joe"
}Deleting users
To delete a user from the server, send a DELETE request to its URL. You must provide the X-Tiggzi-Session-Token header to authenticate. For example:
curl -X DELETE \
-H "X-Tiggzi-Database-Id: 4ffcf6c8e4b0211629c4ad01" \
-H "X-Tiggzi-Session-Token: 80aeb50a-14de-4fd2-9c8e-11c5b60d8959" \
https://api.tiggzi.com/rest/1/db/users/[user_id]
Security
When you access Tiggzi DB via the REST API key, access can be restricted by ACL. You can still read and modify acls via the REST API, just be accessing the “ACL” key of an object.
The ACL is formatted as a JSON object where the keys are either object ids or the special key “*” to indicate public access permissions. The values of the ACL are “permission objects”, JSON objects whose keys are the permission name and the value is always true.
For example, if you want the user with id “4ffcfd9fe4b0211629c4ad06″ to have read and write access to an object, plus the object should be publicly readable, that corresponds to an ACL of:
{
"4ffcfd9fe4b0211629c4ad06": { "read": true, "write": true },
"*": { "read": true }
}