Get started using App Services. Here you'll learn how to perform some basic operations with App Services.
If you haven’t already done so:
- Sign up for an App Services account.
- Click the activation link in the activation email that is sent to you. A default app called "sandbox" will be created for you to test with.
- Install the SDK or module appropriate for your application environment:
Making API requests
App Services uses a REST API. To request an operation through the API, you specify the path to the API endpoint that represents the target resource of the operation, and an HTTP method for the requested action (that is, GET, POST, PUT, or DELETE). Some operations also require you to provide a JSON request body.
The path for all application-related operations, such as creating, updating, or querying entities or collections, begins with the following (if you’re wondering what entities and collections are, see "Creating an entity in a collection" below):
http://api.usergrid.com/{org_id}/{app_id}
where {org_id} is the name or UUID of your organization, and {app_id} is the name or UUID of the application. You can’t mix names and UUIDs. Either specify the names of your organization and application, or specify the UUIDs of your organization and application. For example, suppose your organization name is my-org and your app name is sandbox (that is, the default test app). Suppose too, that within that application an entity named dino exists in a collection named dogs. Here’s the format of the request to retrieve the entity:
GET http://api.usergrid.com/my-org/sandbox/dogs/dino
The actual code you specify in your app to construct an API request depends on the client language you choose. The basic operations covered in the following sections show code examples in the following formats:
- cURL
- JavaScript (HTML5)
- Ruby
- Node.js
See the following Readme files for further information:
Creating an entity in a collection
Entities are simple objects you may want to use in your app, such as cats, stores, and books. Entities of the same type are grouped in a collection: all the cats entities are in the cats collection (if you’ve used a relational database before, you can think of collections as tables, and of entities as rows inside that table).
You don’t have to first create the collection. Simply creating an entity of a certain type will create a collection for you if it doesn’t exist already. When you create the entity, you can specify one or more properties for that entity, for example, the cat’s name, a book’s author, or a store’s location. Most of these properties are decided by you, and do not have to be present for every entity in a collection. This means you can decide that some cats have no names, some books have two authors or some stores have locations in GPS coordinates while others have locations in a "city, state" format.
Some properties will be created automatically for you, such as a unique uuid identifier, the created and modified dates, and a few other pieces of metadata. Other properties are reserved, or special. The type property indicates which collection the entity is in. There’s also the name property, which you can use as a shortcut to retrieve the object ("give me the cat named nico"). As such, each name must be unique in a collection (there can only be one cat named nico). The name is also immutable, so it can't be changed once you specify it — but don’t worry, the other properties can be changed, and outside of special properties, don’t have to be unique.
Here’s how to create an entity named nico in a collection named cats:
curl -X POST "https://api.usergrid.com/my-org/sandbox/cats" -d '{"name":"nico"}'
Note: If you issue a cURL request in a Windows command line, you need to escape any data provided in the request body. For example, here is how how to escape the data in the above cURL command:
curl -X POST "https://api.usergrid.com/my-org/sandbox/cats" -d '{"\name\":"\nico\"}'
Alternatively, you can submit cURL commands through Cygwin, in which case, you do not have to escape the data in the request body.
The example assumes use of the JavaScript (HTML5) SDK.
var options = {
type:'cats',
name:'nico'
}
client.createEntity(options, function (err, cat) {
if (err) {
error('entity not created');
} else {
success('entity created');
cat.save(function(err){
if (err){
//error
} else {
//success
}
});
}
});
The example assumes use of the Ruby SDK.
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/sandbox/' result = app.create_cat name: 'nico' mynewcat = result.entity
The example assumes use of the Node.js module.
var options = {
type:'cats’,
name:'nico'
}
client.createEntity(options, function (err, cat) {
if (err) {
error('entity not created');
} else {
success('entity created');
cat.save(function(err){
if (err){
//error
} else {
//success
}
});
}
});
Learn more about entities and collections in Data model.
Retrieving an entity from a collection
You can retrieve an entity by its name or UUID. Here’s how to retrieve the entity named nico from the cats collection. Assume that the UUID for the entity is 187d31d9-0742-11e2-a7b5-12313d21509c.
Retrieve by name:
curl -X GET "https://api.usergrid.com/my-org/sandbox/cats/nico"
Retrieve by UUID:
curl -X GET "https://api.usergrid.com/my-org/sandbox/cats/187d31d9-0742-11e2-a7b5-12313d21509c"
The example assumes use of the JavaScript (HTML5) SDK.
Retrieve by name:
var options = {
method:'GET',
endpoint:'cats/nico'
};
client.request(options, function (err, data) {
if (err) {
//error
} else {
//success
}
});
Retrieve by UUID:
var options = {
method:'GET',
endpoint:'cats/187d31d9-0742-11e2-a7b5-12313d21509c'
};
client.request(options, function (err, data) {
if (err) {
//error
} else {
//success
}
});
The example assumes use of the Ruby SDK.
Retrieve by name:
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/sandbox/' user = app['cats/nico'].entity
Retrieve by UUID:
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/sandbox/' cat = app['cats/187d31d9-0742-11e2-a7b5-12313d21509c'].entity
The example assumes use of the Node.js module.
Retrieve by name:
var options = {
method:'GET',
endpoint:'cats/nico'
};
client.request(options, function (err, data) {
if (err) {
//error
} else {
//success
}
});
Retrieve by UUID:
var options = {
method:'GET',
endpoint:'cats/187d31d9-0742-11e2-a7b5-12313d21509c'
};
client.request(options, function (err, data) {
if (err) {
//error
} else {
//success
}
});
Creating a user
Users are a special collection. The users collection behaves much like any other collection you would create, but comes with automatic methods to do things such as securely save the password, and look up people by email address.
For a user entity, the username property is immutable (instead of the name property), and must be unique within the users collection (no two users can have the same username).
Here’s how to create a user named John Doe in the users collection. The user has a username of john.doe, an email address of john.doe@gmail.com, and a password of test1234.
curl -X POST "https://api.usergrid.com/my-org/sandbox/users" -d '{"username":"john.doe","email":"john.doe@gmail.com","name":"John Doe","password":"test1234"}'
The example assumes use of the JavaScript (HTML5) SDK.
var options = {
method:'POST',
endpoint:'users',
body:{ username:'john.doe', name:'John Doe', email:'john.doe@gmail.com', password:'test1234' }
};
client.request(options, function (err, data) {
if (err) {
//error
} else {
//success
}
});
The example assumes use of the Ruby SDK.
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/sandbox/' result = app.create_user username: 'john.doe', name: 'John Doe', email: 'john.doe@gmail.com', password: 'test1234' john_doe = result.entity
The example assumes use of the Node.js module.
var options = {
method:'POST',
endpoint:'users',
body:{ username:'john.doe', name:'John Doe', email:'john.doe@gmail.com', password:'test1234' }
};
client.request(options, function (err, data) {
if (err) {
//error
} else {
//success
}
});
Authenticating
For more secure apps, we recommend you always use authentication to access App Services. In fact most apps require authentication by default. (An exception to this is the sandbox app. For ease of use, the sandbox app has all authentication disabled. Users can access resources in the sandbox app without specifying an access token, and because of this, the sandbox app should be used for learning or testing purposes only.)
We also recommend that you always have your app authenticate as the end user (that is, the person using the app or device), rather than with a superuser or application-wide token. This will help you build a very secure app, as well as take advantage of the advanced permission, privacy, and social features provided by App Services.
Suppose you created an app named my-app in the my-org organization, here’s how a user whose username is john.doe and whose password is test1234 would obtain an access token:
curl -X GET "https://api.usergrid.com/management/token?grant_type=password&username=john.doe&password=test1234"
The example assumes use of the JavaScript (HTML5) SDK.
username = 'john.doe';
password = 'test1234';
client.login(username, password,
function (err) {
if (err) {
//error
} else {
//success
var token = client.token;
}
}
);
The example assumes use of the Ruby SDK.
app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/' app.login 'john.doe', 'test1234' token = app.auth_token
The example assumes use of the Node.js module.
username = 'john.doe';
password = 'test1234';
client.login(username, password,
function (err) {
if (err) {
//error
} else {
//success
var token = client.token;
}
}
);
Learn more about Authentication and access in App Services.
Next steps
Ready to learn and do more?
- Download and examine the App Services code examples.
- Review the Developer Guide for information on App Services concepts and features.
- Consult the API Reference for usage details.
