Overview

Apigee App Services is a hosted cloud service to store, retrieve & query your data — and so much more. Create a user record in our database and boom — we automatically give you a method to let that user sign-in to the service (using OAuth), let him own other pieces of data, post stuff to his activity wall, and the ability to become friends & share data with other users — without you having to write a single line of code. Want to store arbitrary data (cats, dogs, cars, songs, …)? If you can express it as JSON, we can store it! We also offer geoindexing and geoqueries out of the box, sign-in with Facebook, automatic full-text querying (with a SQL-compatible language), file upload in a single call (images, videos, songs, etc.) and lots more!

Here’s how to get started with Apigee App Services and Node.js!

Installing

To install the Usergrid Node.js SDK, use the NPM:

$ npm install usergrid-sdk

Or visit the github repo:

https://github.com/apigee/usergrid-node-js-sdk

Getting started

To get you started, please note that the SDK consists of one main JavaScript file, located in the project at:

/lib/usergrid-sdk.js

Simply include the SDK to begin to use it:

var sdk = require('usergrid-sdk');

Then initialize it with your app and org id:

sdk.ApiClient.init('apigee', 'nodejs');

You are now ready to use the sdk handle to make calls against the API. For example, you may want to set your client id and Secret:

sdk.ApiClient.setClientSecretCombo('b3U6y6hRJufDEeGW9hIxOwbREg', 'b3U6ZOaOexFiy6Jh61H4M7p2uFI3h18');

If you are using the client secret and id, you will also want to enable that (client) authentication method:

sdk.ApiClient.enableClientSecretAuth();

Entities and Collections

Entities and Collections are used to model the custom data you need to store in your app. To enable you to use these in your app, the Node SDK provides the Entity and the Collection objects. The following sections describe how to create and use these objects and show examples from a sample app about dogs.

The Entity Object

Start by creating a new Entity object, where the argument is the name of the collection that the entity will be part of. In the Dogs sample app, here is how a new dogs entity is created in a collection named dogs:

var dog = new sdk.Entity("dogs");

Next, add any needed custom fields. For example:

dog.set("name","Dino");
dog.set("owner","Fred");
dog.set("state","hungry");

After the object is complete, save it back to the API, for example:

dog.save();

When the entity is saved, the API gives it a UUID that uniquely identifies the entity in the database. This UUID is stored in the Entity object and will be used for any future calls to the API. This ensures that the correct entity is updated. For example, the UUID is used if the object is updated and needs to be saved again:

dog.set("state", "fed");
dog.save(); //updates the same dog entity as before

Or, if the entity is changed in the database (perhaps by another user of your app), and needs to be refreshed:

dog.fetch(); //will only work if the UUID for the entity is in the dog object

In this way, multiple clients can update the same object in the database.

If you need to get a property from the object, call the get() method and provide the property as an argument to the method, for example:

var state = dog.get("state");

If you no longer need the object, call the destroy() method. This deletes the object from database. For example:

dog.destroy(); //no real dogs were harmed!

Although the object is deleted from the database, it remains in your program. Destroy it if needed by setting it to a null value, for example:

dog = null; //no real dogs were harmed!

The Collection Object

The Collection Object models the custom collections you create using the API. Collections organize entities. For example, you could create a collection called “dogs”. Then, you can add “dog” entities to it.

To get started, create a new Collection object, where the argument is the type of collection you intend to model. For example:

var dogs = new sdk.Collection('dogs'); //makes a new 'dogs' collection object

If your collection already exists on the server, call the get() method to populate your new object with data from the server. For example:

dogs.get();

By default, the dogs.get() method uses the API to retrieve the first 10 dog entities and loads them into the dogs Collection object. If you want to add a new entity to the collection, simply create it. For example:

var dog = new sdk.Entity("dogs");
dog.set("name","fido");

Then add it to the collection (and save it to the API):

dog.addNewEntity(dog);

Note: The addNewEntity() method adds the entity to the collection and also saves it to the API. If you have already saved an entity, you can simply call the addEntity() method.

So this:

var dog = new sdk.Entity("dogs");
dog.save();
dogs.addEntity(dog); //entity is added only

Is equivalent to this:

var dog = new sdk.Entity("dogs");
dogs.addNewEntity(dog); //entity is added and saved

Displaying Results

After you populate your Collection object, you can display a list of all the entities currently stored in the Collection object. Here’s how it’s done in the Dogs app:

//iterate through all the items in this "page" of data
while(dogs.hasNextEntity()) {
    //get a reference to the dog
    var dog = dogs.getNextEntity();
    //do something with the next dog in the list
    //value is in dog.get('name');
}

Note: This code snippet only loops through the items currently stored in the Collection object. If there are more entities in the database that you want to display, either use paging, or a custom query.

Custom Queries

A custom query allows you to tell the API that you want your results filtered or altered in some way. The following example specifies that the query results should be ordered by creation date:

dogs.setQueryParams({'ql':'order by created DESC'});

If you also wanted to get more entities in the result set than the default 10, say 100, you can specify a query similar to the the following (the limit can be a maximum of 999):

dogs.setQueryParams({'ql':'order by created DESC','limit':'100'});

There are many cases where expanding the result set is useful. But be careful - the more results you get back in a single call, the longer it will take to transmit the data back to your app.

You can find more information on custom queries here:

http://apigee.com/docs/usergrid/content/queries-and-parameters

Learn More

We have a full README for our SDK with more examples, explanations on how to use advanced features like user management, access other endpoints and a sample app you can clone.

Signing up & Getting Help during the KO

To sign up during the knockout, please go here.

We also have full service docs.

If you need any help during the weekend, you can ping Rod on IRC (rockerston in #nodeknockout on Freenode) GTalk (rsimpson@apigee.com), email (rsimpson@apigee.com) or Skype (rockerston).

We are also currently looking for cool apps using Node and Apigee App Services, so if you’re building something interesting, please send us an email to be eligible for Apigee’s $4,000 accelerator prize — you must submit your (finished) app by email between now and midnight Pacific on November 30, 2012. Feel free to contact us beforehand for more details or to tell us about what you’re building!