Readme: Clean up of code formatting, some grammar fixes, added UsergridQuery
Project: http://git-wip-us.apache.org/repos/asf/usergrid-nodejs/repo Commit: http://git-wip-us.apache.org/repos/asf/usergrid-nodejs/commit/ee50d70e Tree: http://git-wip-us.apache.org/repos/asf/usergrid-nodejs/tree/ee50d70e Diff: http://git-wip-us.apache.org/repos/asf/usergrid-nodejs/diff/ee50d70e Branch: refs/heads/master Commit: ee50d70e3ff6056ae2f2b35c41e795b75a9346e1 Parents: 46c3df7 Author: brandon <[email protected]> Authored: Thu Feb 11 12:39:31 2016 -0800 Committer: brandon <[email protected]> Committed: Thu Feb 11 12:39:31 2016 -0800 ---------------------------------------------------------------------- README.md | 830 +++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 535 insertions(+), 295 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/usergrid-nodejs/blob/ee50d70e/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 3a7e640..efc0ce2 100644 --- a/README.md +++ b/README.md @@ -53,172 +53,190 @@ There are two different ways of initializing the Usergrid Node.js SDK: 1. The singleton pattern is both convenient and enables the developer to use a globally available and always-initialized shared instance of Usergrid. - var Usergrid = require('usergrid') - Usergrid.init({ - orgId: '<org-id>', - appId: '<app-id>' - }) + ```js + var Usergrid = require('usergrid') + Usergrid.init({ + orgId: '<org-id>', + appId: '<app-id>' + }) - // or you can load from a config file; see config.sample.json + // or you can load from a config file; see config.sample.json - var Usergrid = require('usergrid') - Usergrid.init() // defaults to use config.json + var Usergrid = require('usergrid') + Usergrid.init() // defaults to use config.json + ``` 2. The instance pattern enables the developer to manage instances of the Usergrid client independently and in an isolated fashion. The primary use-case for this is when an application connects to multiple Usergrid targets. - var UsergridClient = require('./node_modules/usergrid/lib/client') - var client = new UsergridClient(config) + ```js + var UsergridClient = require('./node_modules/usergrid/lib/client') + var client = new UsergridClient(config) + ``` _**Note:** Examples in this readme assume you are using the `Usergrid` shared instance. If you've implemented the instance pattern instead, simply replace `Usergrid` with your client instance variable. See `/tests` for additional examples._ ## RESTful operations -When making any RESTful call, a `type` parameter (or `path`) is always required. Whether you specify this as an argument or in an object as a parameter is up to you. +When making any RESTful call, a `type` parameter (or `path`) is always required. Whether you specify this as an argument, in an object as a parameter, or as part of a `UsergridQuery` object is up to you. ### GET() -**GET entities in a collection** - - Usergrid.GET('collection', function(error, usergridResponse, entities) { - // entities is an array of UsergridEntity objects - }) - -**GET a specific entity in a collection by uuid or name** - - Usergrid.GET('collection', '<uuid-or-name>', function(error, usergridResponse, entity) { - // entity, if found, is a UsergridEntity object - }) - -**GET specific entities in a collection by passing a UsergridQuery object** - - var query = new UsergridQuery('cats') - .gt('weight', 2.4) - .contains('color', 'bl*') - .not - .eq('color', 'blue') - .or - .eq('color', 'orange') - - // this will build out the following query: - // select * where weight > 2.4 and color contains 'bl*' and not color = 'blue' or color = 'orange' - - Usergrid.GET(query, function(error, usergridResponse) { - // entities is an array of UsergridEntity objects matching the specified query - }) +To get entities in a collection: + +```js +Usergrid.GET('collection', function(error, usergridResponse, entities) { + // entities is an array of UsergridEntity objects +}) +``` + +To get a specific entity in a collection by uuid or name: + +```js +Usergrid.GET('collection', '<uuid-or-name>', function(error, usergridResponse, entity) { + // entity, if found, is a UsergridEntity object +}) +``` + +To get specific entities in a collection by passing a UsergridQuery object: + +```js +var query = new UsergridQuery('cats') + .gt('weight', 2.4) + .contains('color', 'bl*') + .not + .eq('color', 'blue') + .or + .eq('color', 'orange') + +// this will build out the following query: +// select * where weight > 2.4 and color contains 'bl*' and not color = 'blue' or color = 'orange' + +Usergrid.GET(query, function(error, usergridResponse) { + // entities is an array of UsergridEntity objects matching the specified query +}) +``` ### POST() and PUT() POST and PUT requests both require a JSON body payload. You can pass either a standard JavaScript object or a `UsergridEntity` instance. While the former works in principle, best practise is to use a `UsergridEntity` wherever practical. When an entity has a uuid or name property and already exists on the server, use a PUT request to update it. If it does not, use POST to create it. -**POST (create) a new entity in a collection** +To create a new entity in a collection (POST): - var entity = new UsergridEntity({ - type: 'restaurant', - restaurant: 'Dino's Deep Dish, - cuisine: 'pizza' - }) - - // or +```js +var entity = new UsergridEntity({ + type: 'restaurant', + restaurant: 'Dino's Deep Dish, + cuisine: 'pizza' +}) - var entity = { - type: 'restaurant', - restaurant: 'Dino's Deep Dish, - cuisine: 'pizza' - } +// or - Usergrid.POST(entity, function(error, usergridResponse, entity) { - // entity should now have a uuid property and be created - }) +var entity = { + type: 'restaurant', + restaurant: 'Dino's Deep Dish, + cuisine: 'pizza' +} - // you can also POST an array of entities: - - var entities = [ - new UsergridEntity({ - type: 'restaurant', - restaurant: 'Dino's Deep Dish, - cuisine: 'pizza' - }), - new UsergridEntity({ - type: 'restaurant', - restaurant: 'Pizza da Napoli', - cuisine: 'pizza' - }) - ] - - Usergrid.POST(entities, function(error, usergridResponse, entities) { - // - }) +Usergrid.POST(entity, function(error, usergridResponse, entity) { + // entity should now have a uuid property and be created +}) -**PUT (update) an entity in a collection** +// you can also POST an array of entities: - var entity = new UsergridEntity({ +var entities = [ + new UsergridEntity({ + type: 'restaurant', + restaurant: 'Dino's Deep Dish, + cuisine: 'pizza' + }), + new UsergridEntity({ type: 'restaurant', restaurant: 'Pizza da Napoli', cuisine: 'pizza' }) - - Usergrid.POST(entity, function(error, usergridResponse, entity) { - entity.owner = 'Mia Carrara' - Usergrid.PUT(entity, function(error, usergridResponse, entity) { - // entity now has the property 'owner' - }) - }) - - // or update a set of entities by passing a UsergridQuery object - - var query = new UsergridQuery('restaurants') - .eq('cuisine', 'italian') - - // this will build out the following query: - // select * where cuisine = 'italian' - - Usergrid.PUT(query, { keywords: ['pasta'] }, function(error, usergridResponse) { - /* the first 10 entities matching this query criteria will be updated: - e.g.: - [ - { - "type": "restaurant", - "restaurant": "Il Tarazzo", - "cuisine": "italian", - "keywords": [ - "pasta" - ] - }, - { - "type": "restaurant", - "restaurant": "Cono Sur Pizza & Pasta", - "cuisine": "italian", - "keywords": [ - "pasta" - ] - } - ] - /* - }) +] + +Usergrid.POST(entities, function(error, usergridResponse, entities) { + // +}) +``` + +To update an entity in a collection (PUT request): + +```js +var entity = new UsergridEntity({ + type: 'restaurant', + restaurant: 'Pizza da Napoli', + cuisine: 'pizza' +}) + +Usergrid.POST(entity, function(error, usergridResponse, entity) { + entity.owner = 'Mia Carrara' + Usergrid.PUT(entity, function(error, usergridResponse, entity) { + // entity now has the property 'owner' + }) +}) + +// or update a set of entities by passing a UsergridQuery object + +var query = new UsergridQuery('restaurants') + .eq('cuisine', 'italian') + +// this will build out the following query: +// select * where cuisine = 'italian' + +Usergrid.PUT(query, { keywords: ['pasta'] }, function(error, usergridResponse) { + /* the first 10 entities matching this query criteria will be updated: + e.g.: + [ + { + "type": "restaurant", + "restaurant": "Il Tarazzo", + "cuisine": "italian", + "keywords": [ + "pasta" + ] + }, + { + "type": "restaurant", + "restaurant": "Cono Sur Pizza & Pasta", + "cuisine": "italian", + "keywords": [ + "pasta" + ] + } + ] + /* +}) +``` ### DELETE() DELETE requests require either a specific entity or a `UsergridQuery` object to be passed as an argument. -**DELETE a specific entity in a collection by uuid or name** +To delete a specific entity in a collection by uuid or name: - Usergrid.DELETE('collection', '<uuid-or-name>', function(error, usergridResponse) { - // if successful, entity will now be deleted - }) +```js +Usergrid.DELETE('collection', '<uuid-or-name>', function(error, usergridResponse) { + // if successful, entity will now be deleted +}) +``` -**DELETE specific entities in a collection by passing a UsergridQuery object** +To specific entities in a collection by passing a `UsergridQuery` object: - var query = new UsergridQuery('cats') - .eq('color', 'black') - .or - .eq('color', 'white') - - // this will build out the following query: - // select * where color = 'black' or color = 'white' +```js +var query = new UsergridQuery('cats') + .eq('color', 'black') + .or + .eq('color', 'white') + +// this will build out the following query: +// select * where color = 'black' or color = 'white' - Usergrid.DELETE(query, function(error, usergridResponse) { - // the first 10 entities matching this query criteria will be deleted - }) +Usergrid.DELETE(query, function(error, usergridResponse) { + // the first 10 entities matching this query criteria will be deleted +}) +``` ## Entity operations and convenience methods @@ -226,22 +244,34 @@ DELETE requests require either a specific entity or a `UsergridQuery` object to ### reload() - entity.reload(function(error, usergridResponse) { - // entity is now reloaded from the server - }) +Reloads the entity from the server + +```js +entity.reload(function(error, usergridResponse) { + // entity is now reloaded from the server +}) +``` ### save() - entity.aNewProperty = 'A new value' - entity.save(function(error, usergridResponse) { - // entity is now updated on the server - }) +Saves (or creates) the entity on the server + +```js +entity.aNewProperty = 'A new value' +entity.save(function(error, usergridResponse) { + // entity is now updated on the server +}) +``` ### remove() - entity.remove(function(error, usergridResponse) { - // entity is now deleted on the server and the local instance should be destroyed - }) +Deletes the entity from the server + +```js +entity.remove(function(error, usergridResponse) { + // entity is now deleted on the server and the local instance should be destroyed +}) +``` ## Authentication, current user, and auth-fallback @@ -249,10 +279,12 @@ DELETE requests require either a specific entity or a `UsergridQuery` object to `Usergrid` can use the app client ID and secret that were passed upon initialization and automatically retrieve an app-level token for these credentials. - Usergrid.setAppAuth('<client-id>', '<client-secret>') - Usergrid.authenticateApp(function(error, usergridResponse, token) { - // Usergrid.appAuth is created automatically when this call is successful - }) +```js +Usergrid.setAppAuth('<client-id>', '<client-secret>') +Usergrid.authenticateApp(function(error, usergridResponse, token) { + // Usergrid.appAuth is created automatically when this call is successful +}) +``` ### authFallback @@ -262,36 +294,42 @@ Auth-fallback defines what the client should do when a user token is not present At times it is desireable to have complete, granular control over the authentication context of an API call. To facilitate this, the passthrough function `.usingAuth()` allows you to pre-define the auth context of the next API call. - // assume Usergrid.authFallback = UsergridAuth.AUTH_FALLBACK_NONE +```js +// assume Usergrid.authFallback = UsergridAuth.AUTH_FALLBACK_NONE - Usergrid.usingAuth(Usergrid.appAuth).POST('roles/guest/permissions', { - permission: "get,post,put,delete:/**" - }, function(error, usergridResponse) { - // here we've temporarily used the client credentials to modify permissions - // subsequent calls will not use this auth context - }) +Usergrid.usingAuth(Usergrid.appAuth).POST('roles/guest/permissions', { + permission: "get,post,put,delete:/**" +}, function(error, usergridResponse) { + // here we've temporarily used the client credentials to modify permissions + // subsequent calls will not use this auth context +}) +``` ### currentUser and authenticateUser() `Usergrid` has a special `currentUser` property. By default, when calling `authenticateUser()`, `.currentUser` will be set to this user if the authentication flow is successful. - Usergrid.authenticateUser({ - username: '<username>', - email: '<email-address>', // either username or email is required - password: '<password>' - }, function(error, usergridResponse, token) { - // Usergrid.currentUser is set to the authenticated user and the token is stored within that context - }) +```js +Usergrid.authenticateUser({ + username: '<username>', + email: '<email-address>', // either username or email is required + password: '<password>' +}, function(error, usergridResponse, token) { + // Usergrid.currentUser is set to the authenticated user and the token is stored within that context +}) +``` If you want to utilize authenticateUser without setting as the current user, simply pass a `false` boolean value as the second parameter: - Usergrid.authenticateUser({ - username: '<username>', - email: '<email-address>', // either username or email is required - password: '<password>' - }, false, function(error, usergridResponse, token) { +```js +Usergrid.authenticateUser({ + username: '<username>', + email: '<email-address>', // either username or email is required + password: '<password>' +}, false, function(error, usergridResponse, token) { - }) +}) +``` ## User operations and convenience methods @@ -301,78 +339,258 @@ If you want to utilize authenticateUser without setting as the current user, sim Creating a new user: - var user = new UsergridUser({ - username: 'username', - password: 'password' - }) +```js +var user = new UsergridUser({ + username: 'username', + password: 'password' +}) - user.create(function(error, usergridResponse, user) { - // user has now been created and should have a valid uuid - }) +user.create(function(error, usergridResponse, user) { + // user has now been created and should have a valid uuid +}) +``` ### login() A simpler means of retrieving a user-level token: - var user = new UsergridUser({ - username: 'username', - password: 'password' - }) +```js +var user = new UsergridUser({ + username: 'username', + password: 'password' +}) - user.login(function(error, usergridResponse, token) { - // user is now logged in - }) +user.login(function(error, usergridResponse, token) { + // user is now logged in +}) +``` ### logout() Logs out the selected user. You can also use this convenience method on `Usergrid.currentUser`. - user.logout(function(error, usergridResponse) { - // user is now logged out - }) +```js +user.logout(function(error, usergridResponse) { + // user is now logged out +}) +``` ### logoutAllSessions() Logs out all sessions for the selected user and destroys all active tokens. You can also use this convenience method on `Usergrid.currentUser`. - user.logoutAllSessions(function(error, usergridResponse) { - // user is now logged out from everywhere - }) +```js +user.logoutAllSessions(function(error, usergridResponse) { + // user is now logged out from everywhere +}) +``` ### resetPassword() Resets the password for the selected user. - user.resetPassword({ - oldPassword: '2cool4u', - newPassword: 'correct-horse-battery-staple', - }, function(error, response, success) { - // if it was done correctly, the new password will be changed - // 'success' is a boolean value that indicates whether it was changed successfully - }) +```js +user.resetPassword({ + oldPassword: '2cool4u', + newPassword: 'correct-horse-battery-staple', +}, function(error, response, success) { + // if it was done correctly, the new password will be changed + // 'success' is a boolean value that indicates whether it was changed successfully +}) +``` ### UsergridUser.CheckAvailable() This is a class (static) method that allows you to check whether a username or email address is available or not. - UsergridUser.CheckAvailable(client, { - email: 'email' - }, function(err, response, exists) { - // 'exists' is a boolean value that indicates whether a user already exists - }) +```js +UsergridUser.CheckAvailable(client, { + email: 'email' +}, function(err, response, exists) { + // 'exists' is a boolean value that indicates whether a user already exists +}) - UsergridUser.CheckAvailable(client, { - username: 'username' - }, function(err, response, exists) { - - }) +UsergridUser.CheckAvailable(client, { + username: 'username' +}, function(err, response, exists) { + +}) - UsergridUser.CheckAvailable(client, { - email: 'email', - username: 'username', // checks both email and username - }, function(err, response, exists) { - // 'exists' returns true if either username or email exist - }) +UsergridUser.CheckAvailable(client, { + email: 'email', + username: 'username', // checks both email and username +}, function(err, response, exists) { + // 'exists' returns true if either username or email exist +}) +``` + +## Querying and filtering data + +### UsergridQuery initialization + +The `UsergridQuery` class allows you to build out complex query filters using the Usergrid [query syntax](http://docs.apigee.com/app-services/content/querying-your-data). + +The first parameter of the `UsergridQuery` builder pattern should be the collection (or type) you intend to query. You can either pass this as an argument, or as the first builder object: + +```js +var query = new UsergridQuery('cats') +// or +var query = new UsergridQuery().type('cats') +var query = new UsergridQuery().collection('cats') +``` + +You then can layer on additional queries: + +```js +var query = new UsergridQuery('cats') + .gt('weight', 2.4) + .contains('color', 'bl*') + .not + .eq('color', 'white') + .or + .eq('color', 'orange') +``` + +You can also adjust the number of results returned: + +```js +var query = new UsergridQuery('cats').eq('color', 'black').limit(100) +// returns a maximum of 100 entiteis +``` + +And sort the results: + +```js +var query = new UsergridQuery('cats').eq('color', 'black').asc('name') +// sorts by 'name', ascending +``` + +And you can do geo-location queries: + +```js +var query = new UsergridQuery('devices').locationWithin(<distanceInMeters>, <latitude>, <longitude>) +``` + +### Using a query in a request + +Queries can be passed as parameters to GET, PUT, and DELETE requests: + +```js +Usergrid.GET(query, function(error, usergridResponse, entities) { + // +}) + +Usergrid.PUT(query, { aNewProperty: "A new value" }, function(error, usergridResponse, entities) { + // +}) + +Usergrid.DELETE(query, function(error, usergridResponse, entities) { + // +}) +``` + +While not a typical use case, sometimes it is useful to be able to create a query that works on multiple collections. Therefore, in each one of these RESTful calls, you can optionally pass a 'type' string as the first argument: + +```js +Usergrid.GET('cats', query, function(error, usergridResponse, entities) { + // +}) +``` + +### List of query builder objects + +`type('string')` + +> The collection name to query + +`collection('string')` + +> An alias for `type` + +`eq('key', 'value')` or `equal('key', 'value')` + +> Equal to (e.g. `where color = 'black'`) + +`contains('key', 'value')` + +> Contains a string (e.g.` where color contains 'bl*'`) + +`gt('key', 'value')` or `greaterThan('key', 'value')` + +> Greater than (e.g. `where weight > 2.4`) + +`gte('key', 'value')` or `greaterThanOrEqual('key', 'value')` + +> Greater than or equal to (e.g. `where weight >= 2.4`) + +`lt('key', 'value')` or `lessThan('key', 'value')` + +> Less than (e.g. `where weight < 2.4`) + +`lte('key', 'value')` or `lessThanOrEqual('key', 'value')` + +> Less than or equal to (e.g. `where weight <= 2.4`) + +`not` + +> Negates the next block in the builder pattern, e.g.: + +```js +var query = new UsergridQuery('cats').not.eq('color', 'black') +// select * from cats where not color = 'black' +``` + +`and` + +> Joins two queries by requiring both of them. `and` is also implied when joining two queries _without_ an operator. E.g.: + +```js +var query = new UsergridQuery('cats').eq('color', 'black').eq('fur', 'longHair') +// is identical to: +var query = new UsergridQuery('cats').eq('color', 'black').and.eq('fur', 'longHair') +``` + +`or` + +> Joins two queries by requiring only one of them. `or` is never implied. E.g.: + +```js +var query = new UsergridQuery('cats').eq('color', 'black').or.eq('color', 'white') +``` + +> When using `or` and `and` operators, `and` joins will take precedence over `or` joins. You can read more about query operators and precedence [here](http://docs.apigee.com/api-baas/content/supported-query-operators-data-types). + +`locationWithin(distanceInMeters, latitude, longitude)` + +> Returns entities which have a location within the specified radius. Arguments can be `float` or `int`. + +`asc('key')` + +> Sorts the results by the specified property, ascending + +`desc('key')` + +> Sorts the results by the specified property, descending + +`sort('key', 'order')` + +> Sorts the results by the specified property, in the specified order (`asc` or `desc`). + +`limit(int)` + +> The maximum number of entities to return + +`cursor('string')` + +> A pagination cursor string + +`fromString('query string')` + +> A special builder property that allows you to input a pre-defined query string. All other builder properties will be ignored when this property is defined. For example: + +```js +var query = new UsergridQuery().fromString("select * where color = 'black' order by name asc") +``` ## UsergridResponse object @@ -382,11 +600,13 @@ This is a class (static) method that allows you to check whether a username or e You can check `usergridResponse.ok`, a `bool` value, to see if the response was successful. Any status code < 400 returns true. - Usergrid.GET('collection', function(error, usergridResponse, entities) { - if (usergridResponse.ok) { - // woo! - } - }) +```js +Usergrid.GET('collection', function(error, usergridResponse, entities) { + if (usergridResponse.ok) { + // woo! + } +}) +``` ### entity, entities, user, users, first, last @@ -400,36 +620,38 @@ Depending on the call you make, you will receive either an array of UsergridEnti Examples: - Usergrid.GET('collection', function(error, usergridResponse, entities) { - // third param is an array of entities because no specific entity was referenced - // you can also access: - // usergridResponse.entities - // usergridResponse.first - // usergridResponse.entity (the first entity) - // usergridResponse.last - }) - - Usergrid.GET('collection', '<uuid or name>', function(error, usergridResponse, entity) { - // third param is a single entity object - // you can also access: - // usergridResponse.entity - // usergridResponse.first - // usergridResponse.last - }) - - Usergrid.GET('users', function(error, usergridResponse, users) { - // third param is an array of users because no specific user was referenced - // you can also access: - // usergridResponse.users - // usergridResponse.user (the first user) - // usergridResponse.last - }) - - Usergrid.GET('users', '<uuid, username, or email>', function(error, usergridResponse, user) { - // third param is a single user object - // you can also access: - // usergridResponse.user - }) +```js +Usergrid.GET('collection', function(error, usergridResponse, entities) { + // third param is an array of entities because no specific entity was referenced + // you can also access: + // usergridResponse.entities + // usergridResponse.first + // usergridResponse.entity (the first entity) + // usergridResponse.last +}) + +Usergrid.GET('collection', '<uuid or name>', function(error, usergridResponse, entity) { + // third param is a single entity object + // you can also access: + // usergridResponse.entity + // usergridResponse.first + // usergridResponse.last +}) + +Usergrid.GET('users', function(error, usergridResponse, users) { + // third param is an array of users because no specific user was referenced + // you can also access: + // usergridResponse.users + // usergridResponse.user (the first user) + // usergridResponse.last +}) + +Usergrid.GET('users', '<uuid, username, or email>', function(error, usergridResponse, user) { + // third param is a single user object + // you can also access: + // usergridResponse.user +}) +``` ## Connections @@ -437,35 +659,42 @@ Connections can be managed using `Usergrid.connect()`, `Usergrid.disconnect()`, ### connect -**Create a connection between two entities** +Create a connection between two entities: - Usergrid.connect(entity1, 'relationship', entity2, function(error, usergridResponse) { - // entity1 now has an outbound connection to entity2 - }) +```js +Usergrid.connect(entity1, 'relationship', entity2, function(error, usergridResponse) { + // entity1 now has an outbound connection to entity2 +}) +``` ### getConnections -**Retrieve outbound connections** +Retrieve outbound connections: - client.getConnections(UsergridClient.Connections.DIRECTION_OUT, entity1, 'relationship', function(error, usergridResponse, entities) { - // entities is an array of entities that entity1 is connected to via 'relationship' - // in this case, we'll see entity2 in the array - }) +```js +client.getConnections(UsergridClient.Connections.DIRECTION_OUT, entity1, 'relationship', function(error, usergridResponse, entities) { + // entities is an array of entities that entity1 is connected to via 'relationship' + // in this case, we'll see entity2 in the array +}) +``` -**Retrieve inbound connections** +Retrieve inbound connections: - client.getConnections(UsergridClient.Connections.DIRECTION_IN, entity2, 'relationship', function(error, usergridResponse, entities) { - // entities is an array of entities that connect to entity2 via 'relationship' - // in this case, we'll see entity1 in the array - }) +```js +client.getConnections(UsergridClient.Connections.DIRECTION_IN, entity2, 'relationship', function(error, usergridResponse, entities) { + // entities is an array of entities that connect to entity2 via 'relationship' + // in this case, we'll see entity1 in the array +})``` ### disconnect -**Delete a connection between two entities** +Delete a connection between two entities: - Usergrid.disconnect(entity1, 'relationship', entity2, function(error, usergridResponse) { - // entity1's outbound connection to entity2 has been destroyed - }) +```js +Usergrid.disconnect(entity1, 'relationship', entity2, function(error, usergridResponse) { + // entity1's outbound connection to entity2 has been destroyed +}) +``` ## Assets @@ -473,59 +702,70 @@ Assets can be uploaded and downloaded either directly using `Usergrid.POST` or ` ### UsergridAsset init -**Loading a file system image via `fs.readFile()`** +Loading a file system image via `fs.readFile()`: - var asset = new UsergridAsset('myImage') - fs.readFile(_dirname + '/image.jpg', function(error, data) { - asset.data = data - }) +```js +var asset = new UsergridAsset('myImage') +fs.readFile(_dirname + '/image.jpg', function(error, data) { + asset.data = data +}) +``` -**Loading a file system image from a read stream (`fs.createReadStream()`)** +Loading a file system image from a read stream (`fs.createReadStream()`): - var asset = new UsergridAsset('myImage') - fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { - // now contains Buffer stream at asset.data - }) +```js +var asset = new UsergridAsset('myImage') +fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { + // now contains Buffer stream at asset.data +}) +``` You can also access `asset.contentType` and `asset.contentLength` once data has been loaded into a `UsergridAsset`. ### .POST and .PUT -**POST binary data to a collection by creating a new entity** +POST binary data to a collection by creating a new entity: - var asset = new UsergridAsset('myImage') - fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { - client.POST('collection', asset, function(error, assetResponse, entityWithAsset) { - // asset is now uploaded to Usergrid - }) +```js +var asset = new UsergridAsset('myImage') +fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { + client.POST('collection', asset, function(error, assetResponse, entityWithAsset) { + // asset is now uploaded to Usergrid }) +}) +``` -**PUT binary data to an existing entity via attachAsset()** +PUT binary data to an existing entity via attachAsset(): - var asset = new UsergridAsset('myImage') - fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { - // assume entity already exists; attach it to the entity: - entity.attachAsset(asset) - client.PUT(entity, asset, function(error, assetResponse, entityWithAsset) { - // asset is now uploaded to Usergrid - }) +```js +var asset = new UsergridAsset('myImage') +fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { + // assume entity already exists; attach it to the entity: + entity.attachAsset(asset) + client.PUT(entity, asset, function(error, assetResponse, entityWithAsset) { + // asset is now uploaded to Usergrid }) +}) +``` ### UsergridEntity convenience methods -**entity.uploadAsset() is a much simpler means of uploading an asset** +`entity.uploadAsset()` is a convenient way to upload an asset that is attached to an entity: - var asset = new UsergridAsset('myImage') - fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { - // assume entity already exists; attach it to the entity: - entity.attachAsset(asset) - entity.uploadAsset(function(error, assetResponse, entityWithAsset) { - // asset is now uploaded to Usergrid - }) +```js +var asset = new UsergridAsset('myImage') +fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { + // assume entity already exists; attach it to the entity: + entity.attachAsset(asset) + entity.uploadAsset(function(error, assetResponse, entityWithAsset) { + // asset is now uploaded to Usergrid }) +}) +``` -**entity.downloadAsset() allows you to download a binary asset** +`entity.downloadAsset()` allows you to download a binary asset: - entity.uploadAsset(function(error, assetResponse, entityWithAsset) { - // access the asset via entityWithAsset.asset - }) +```js +entity.uploadAsset(function(error, assetResponse, entityWithAsset) { + // access the asset via entityWithAsset.asset +})```
