TinCan Storage API Demo



Basic Queries

All queries can be made via HTTP or HTTPS, though HTTPS is preferred because it helps keep your credentials secure. They are made via POST (with a couple exceptions), and must contain the following:

POST https://[ID]:[key]@apps.tincan.me/[name]/[type]
"[query string]"

This document will use a dummy application with the following credentials:

Inserting Data

All queries must be JSON encoded objects. To insert data, simply supply a JSON-encoded string as your query:

POST https://5e6a7e38c97b:81aca0b3a200dd52bda8bca268ee68a8@apps.tincan.me/example/insert
{"data": {"name": "John Mitchell", "image": "http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50", "age": 37, "online": true}}

data should contain the data you want to insert. The query should return a JSON document saying {"success": true} to indicate that your query has run successfully. If there is ever an error, the JSON document will have a property called error that describes the problem.

Retrieving Data

To retrieve a document or set of documents, use the "find" query type, and describe the document you're looking for in the query field:

POST https://5e6a7e38c97b:[email protected]/example/find
{"query": {"name": "John Mitchell"}}

The above code will return an object with {"success": true} and an array named "data" containing all matching accounts. In this example, only John's account should be listed. Likewise, the following query will return all online users:

POST https://5e6a7e38c97b:[email protected]/example/find
{"query": {"online": true}}

Note: To retrieve all documents, supply either an empty string or {} for your query. This is also the one instance in which you may use GET on a "find" query.

Retrieving and Manipulating Data

When looking up data, you can supply an extra property in your query called options. The folowing options are currently available:

For example, the following query would list the 5 oldest users that are currently online:

POST https://5e6a7e38c97b:[email protected]/example/find
{"query": {"online": true}, "options": {"sort": {"age": -1}, "limit": 5}}

In the code above, "sort": {"age": -1} tells the database to sort according to the "age" property, descending. Changing -1 to 1 would return the 5 youngest users.

The size and count options cause the output to be an integer rather than a list of actual results. If you don't supply either limit or count as options, size and count will both give the same results. Here's how you could count the number of online users:

POST https://5e6a7e38c97b:[email protected]/example/find
{"query": {"online": true}, "options": {"count": true}}

Changing data

Let's say John has had a birthday, and is now a year older. We can use the "update" query type to change his "age" property a number of ways:

POST https://5e6a7e38c97b:[email protected]/example/update
{"query": {"name": "John Mitchell"}, "data": {"$set": {"age": 38}}}

This time, we supply both a query and data, where query describes the document(s) we're looking for, and data contains our changes. In the previous example, we just overwrote the "age" property with a new value using the $set operator. However, you could also do it like this:

POST https://5e6a7e38c97b:[email protected]/example/update
{"query": {"name": "John Mitchell"}, "data": {"$inc": {"age": 1}}}

In that case, we used the $inc operator to increment the "age" property by 1. There are more operators that can be used, which follow the rules of MongoDB.

Deleting data

Finally, sometimes you want to delete a document. This can be done using the same syntax as a "find" query, but using the "remove" type. To delete John's account, you could do this:

POST https://5e6a7e38c97b:[email protected]/example/remove
{"query": {"name": "John Mitchell"}}

Note: As a safeguard, an empty query will NOT delete all documents. To erase ALL data in your application's database, you can drop it by using the query {"options": {"drop": true}}. You don't need to supply a query attribute, as it will be ignored if this option is present.

Validating credentials

To check the validity of your credentials, use the "authorized" query type, which can be made over either POST or GET and takes no extra parameters:

GET https://5e6a7e38c97b:[email protected]/example/authorized

If your credentials are valid for the given application, it will return {"success": true} with no additional data. In the case of this tutorial, it will return {"success": false, "error": "NO_SUCH_APP"}, since "example" is not a real application. If it were, you would get {"success": false, "error": "INVALID_CREDENTIALS"}, indicating that your credentials are not correct for the given app.

To learn more about different queries, visit the MongoDB reference guide on operators.