TinCan Storage API Demo

Application name:

Application ID:

Application key:

Query type: Find Update Insert Remove Authorized User

Query:

Output

Tutorial

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:

• Application name
• Application ID
• Application key
• Query type
• Query string

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

• Application name: example
• Application ID: 5e6a7e38c97b
• Application key: 81aca0b3a200dd52bda8bca268ee68a8

Inserting Data

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

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:

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:

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:

• limit (integer): Limit output to the given number of results
• skip (integer): Skip the first (n) results
• size (boolean): Output the total number of results that the given query would normally return
• count (boolean): Output the total number of results that the given query would normally return, ignoring limit and count
• sort (object): Sort all results according to the given object. For more details, see the MongoDB docs.

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

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:

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:

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:

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:

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:

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.