WebService Class


Defined in: cloudmine.js.

Class Summary

Constructor Attributes Constructor Name and Description
 
WebService(Default)
Construct a new WebService instance

Each method on the WebService instance will return an APICall object which may be used to access the results of the method called.

Method Summary

Method Attributes Method Name and Description
 
allUsers(options)
Get all user objects.
 
changePassword(data, options)
Change a user's password
 
changePassword(user, oldpassword, password, options)
Change a user's password
 
confirmReset(token, newPassword, options)
Change the password for an account from the token received from password reset.
 
createUser(data, options)
Create a new user.
 
createUser(auth, password, options)
Create a new user.
 
deleteUser(data, options)
Delete a user.
 
deleteUser(email, password, options)
Delete a user.
 
destroy(keys, options)
Destroy one or more keys on the server.
 
download(key, options)
Download a file stored in CloudMine.
 
get(keys, options)
Get data from CloudMine.
 
Get the current email.
 
getOption(option)
Get a default option that is sent to the server.
 
Get the current session token.
 
getUser(id, options)
Get specific user by id.
 
Get the current userid
 
Get the current username.
 
Determine if this store is using application data.
 
Check if the store has a logged in user.
 
login(data, options)
Login as a user to access user-level data.
 
login(auth, password, options)
Login as a user to access user-level data.
 
loginSocial(network, options)
Login a user via a social network credentials.
 
logout(options)
Logout the current user.
 
resetPassword(email, options)
Initiate a password reset request.
 
run(snippet, params, options)
Run a code snippet directly.
 
search(query, options)
Search CloudMine for text objects.
 
searchFiles(query, options)
Search CloudMine explicitly querying for files.
 
searchGeo(field, target, options)
Search using CloudMine's geoquery API.
 
searchUsers(query, options)
Search CloudMine user objects by custom attributes.
 
searchUsers(query, options)
Search CloudMine user objects by custom attributes.
 
set(data, options)
Create or overwrite existing objects in CloudMine with the given key or keys.
 
set(key, value)
Create or overwrite existing objects in CloudMine with the given key or keys.
 
setOption(option, value)
Set a default option that is sent to the server
 
socialQuery(query, options)
Query a social network.
 
update(data, options)
Create new data, and merge existing data.
 
update(key, value, options)
Create new data, and merge existing data.
 
updateUser(data, options)
Update user object of logged in user.
 
updateUser(field, value, options)
Update user object of logged in user.
 
upload(key, file, options)
Upload a file stored in CloudMine.
 
Set the application or user-level data mode for this store.
 
verify(data, options)
Verify if the given login and password is valid.
 
verify(auth, password, options)
Verify if the given email and password is valid.

Class Detail

WebService(Default)
Construct a new WebService instance

Each method on the WebService instance will return an APICall object which may be used to access the results of the method called. You can chain multiple events together with the returned object (an APICall instance).

All events are at least guaranteed to have the callback signature: function(data, apicall). supported events:

200, 201, 400, 401, 404, 409, ok, created, badrequest, unauthorized, notfound, conflict, success, error, complete, meta, result, abort

Event order: success callbacks, meta callbacks, result callbacks, error callbacks, complete callbacks

Example:

var ws = new cloudmine.WebService({appid: "abc", apikey: "abc", appname: 'SampleApp', appversion: '1.0'});
ws.get("MyKey").on("success", function(data, apicall) {
   console.log("MyKey value: %o", data["MyKey"]);
}).on("error", function(data, apicall) {
   console.log("Failed to get MyKey: %o", apicall.status);
}).on("unauthorized", function(data, apicall) {
   console.log("I'm not authorized to access 'appid'");
}).on(404, function(data, apicall) {
   console.log("Could not find 'MyKey'");
}).on("complete", function(data, apicall) {
   console.log("Finished get on 'MyKey':", data);
});

Refer to APICall's documentation for further information on events.

Parameters:
{object} Default
configuration for this WebService
{string} Default.appid Optional
The application id for requests (Required)
{string} Default.apikey Optional
The api key for requests (Required)
{string} Default.appname Optional
An alphanumeric identifier for your app, used for stats purposes
{string} Default.appversion Optional
A version identifier for you app, used for stats purposes
{boolean} Default.applevel Optional
If true, always send requests to application. If false, always send requests to user-level, trigger error if not logged in. Otherwise, send requests to user-level if logged in.
{boolean} Default.savelogin Optional
If true, session token and email / username will be persisted between logins.
{integer} Default.limit Optional
Set the default result limit for requests
{string} Default.sort Optional
Set the field on which to sort results
{integer} Default.skip Optional
Set the default number of results to skip for requests
{boolean} Default.count Optional
Return the count of results for request.
{string} Default.snippet Optional
Run the specified code snippet during the request.
{string|object} Default.params Optional
Parameters to give the code snippet (applies only for code snippets)
{boolean} Default.dontwait Optional
Don't wait for the result of the code snippet (applies only for code snippets)
{boolean} Default.resultsonly Optional
Only return results from the code snippet (applies only for code snippets)

Method Detail

{APICall} allUsers(options)
Get all user objects. Results may be affected by defaults and/or by the options parameter.
Parameters:
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} changePassword(data, options)
Change a user's password
Parameters:
{object} data
An object with email, password, and oldpassword fields.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} changePassword(user, oldpassword, password, options)
Change a user's password
Parameters:
{string} user
The email to change the password.
{string} oldpassword
The existing password for the user.
{string} password
The new password for the user.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} confirmReset(token, newPassword, options)
Change the password for an account from the token received from password reset.
Parameters:
{string} token
The token for password reset. Usually received by email.
{string} newPassword
The password to assign to the user.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} createUser(data, options)
Create a new user.
Parameters:
{object} data
An object with an email, username, and password field.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
{object} options.profile Optional
Create a user with the given user profile.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} createUser(auth, password, options)
Create a new user.
Parameters:
{string} auth
The email to login as.
{string} password
The password to login as.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
{object} options.profile Optional
Create a user with the given user profile.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} deleteUser(data, options)
Delete a user. If you are using the master api key, omit the user password to delete the user. If you are not using the master api key, provide the user name and password in the corresponding email and password fields.
Parameters:
{object} data
An object that may contain email / username fields and optionally a password field.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} deleteUser(email, password, options)
Delete a user. If you are using the master api key, omit the user password to delete the user. If you are not using the master api key, provide the user name and password in the corresponding email and password fields.
Parameters:
{string} email
The email of the user to delete. If using a master key use a user id.
{string} password
The password for the account. Omit if using a master key.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} destroy(keys, options)
Destroy one or more keys on the server. If given null and options.all is true, delete all objects on the server. Results may be affected by defaults and/or by the options parameter.
Parameters:
{string|string[]|null} keys
The keys to delete on the server.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters. Pass all:true with null keys to really delete all values, or query with a query object or string to delete objects matching query. WARNING: using the query is DANGEROUS. Triple check your query!
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} download(key, options)
Download a file stored in CloudMine.
Parameters:
{string} key
The binary file's object key.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
{string} options.filename Optional
If present, the file will be downloaded directly to the computer with the filename given. This does not validate the filename given!
{string} options.mode Optional
If buffer, automatically move returning data to either an ArrayBuffer or Buffer if supported. Otherwise the result will be a standard string.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} get(keys, options)
Get data from CloudMine. Results may be affected by defaults and/or by the options parameter.
Parameters:
{string|string[]|null} keys Optional
If set, return the specified keys, otherwise return all keys.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{string} getEmail()
Get the current email.
Returns:
{string} The logged in email, if logged in.

{*} getOption(option)
Get a default option that is sent to the server.
Parameters:
{string} option
A default parameter to send to the server.
Returns:
{*} The value of the default parameter.

{string} getSessionToken()
Get the current session token.
Returns:
{string} The current session token, if logged in.

{APICall} getUser(id, options)
Get specific user by id.
Parameters:
{string} id
User id being requested.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters. Results may be affected by defaults and/or by the options parameter.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{string} getUserID()
Get the current userid
Returns:
{string} The logged in userid, if applicable.

{string} getUsername()
Get the current username.
Returns:
{string} The logged in username, if logged in.

{boolean} isApplicationData()
Determine if this store is using application data.
Returns:
{boolean} true if this store is using application data, false if is using user-level data.

{boolean} isLoggedIn()
Check if the store has a logged in user.
Returns:
{boolean} True if the user is logged in, false otherwise.

{APICall} login(data, options)
Login as a user to access user-level data.
Parameters:
{object} data
An object hash with email / username, and password fields.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} login(auth, password, options)
Login as a user to access user-level data.
Parameters:
{string} auth
The email of the user to login as
{string} password
The password for the user
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} loginSocial(network, options)
Login a user via a social network credentials. This only works for browsers (i.e. not in a node.js environment) and requires user interaction (a browser window).
Parameters:
{string} network
A network to authenticate against. @see WebService.SocialNetworks
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
{string} options.link Optional
If false, do not link social network to currently logged in user.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} logout(options)
Logout the current user.
Parameters:
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} resetPassword(email, options)
Initiate a password reset request.
Parameters:
{string} email
The email to send a reset password email to.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} run(snippet, params, options)
Run a code snippet directly. Default http method is 'GET', to change the method set the method option for options.
Parameters:
{string} snippet
The name of the code snippet to run.
{object} params
Data to send to the code snippet (optional).
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} search(query, options)
Search CloudMine for text objects. Results may be affected by defaults and/or by the options parameter.
Parameters:
{string} query
Query parameters to search for.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} searchFiles(query, options)
Search CloudMine explicitly querying for files. Note: This does not search the contents of files. Results may be affected by defaults and/or by the options parameter.
Parameters:
{string} query
Additional query parameters to search for.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} searchGeo(field, target, options)
Search using CloudMine's geoquery API.
Parameters:
{string} field
Field to search on.
{object} target
A reference object that has geo-location data.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
{string} options.units Optional, Default: 'km'
The unit to use when not specified for. Can be 'km', 'mi', 'm', 'ft'.
{boolean} options.distance Optional, Default: false
If true, include distance calculations in the meta result for objects.
{string|number} options.radius Optional
Distance around the target. If string, include units. If number, specify the unit in options.unit.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} searchUsers(query, options)
Search CloudMine user objects by custom attributes. Results may be affected by defaults and/or by the options parameter.
Parameters:
{string} query
Additional query parameters to search for in [key="value", key="value"] format.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} searchUsers(query, options)
Search CloudMine user objects by custom attributes. Results may be affected by defaults and/or by the options parameter.
Parameters:
{object} query
Additional query parameters to search for in {key: value, key: value} format.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} set(data, options)
Create or overwrite existing objects in CloudMine with the given key or keys. The data must be convertable to JSON. Results may be affected by defaults and/or by the options parameter.
Parameters:
{object} data
An object hash where the top level properties are the keys.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} set(key, value)
Create or overwrite existing objects in CloudMine with the given key or keys. The data must be convertable to JSON. Results may be affected by defaults and/or by the options parameter.
Parameters:
{string|null} key
The key to affect. If given null, a random key will be assigned.
{string|number|object} value
The object to store.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{boolean} setOption(option, value)
Set a default option that is sent to the server
Parameters:
{string} option
A default parameter to send to the server.
{string} value
The value of the option to set.
Returns:
{boolean} true if the option was set, false for invalid options.

{APICall} socialQuery(query, options)
Query a social network. Must be logged in as a user who has logged in to a social network.
Parameters:
{object} query
An object with the parameters of the query.
{string} query.network
A network to authenticate against. @see WebService.SocialNetworks
{string} query.endpoint
The endpoint to hit, on the social network side. See the social network's documentation for more details.
{string} query.method
HTTP verb to use when querying.
{object} query.headers
Extra headers to pass in the HTTP request to the social network.
{object} query.params
Extra parameters to pass in the HTTP request to the social network.
{string} query.data
Data to pass in the body of the HTTP request.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Throws:
{Error}
If the user is not logged in.
{Error}
If query.headers is truthy and not an object.
{Error}
If query.params is truthy and not an object.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} update(data, options)
Create new data, and merge existing data. The data must be convertable to JSON. Results may be affected by defaults and/or by the options parameter.
Parameters:
{object} data
An object hash where the top level properties are the keys.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} update(key, value, options)
Create new data, and merge existing data. The data must be convertable to JSON. Results may be affected by defaults and/or by the options parameter.
Parameters:
{string|null} key
The key to affect. If given null, a random key will be assigned.
{string|number|object} value
The value of the object
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} updateUser(data, options)
Update user object of logged in user.
Parameters:
{object} data
An object to merge into the logged in user object.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} updateUser(field, value, options)
Update user object of logged in user.
Parameters:
{string} field
The field to merge into the logged in user object.
{string} value
The value to set the field to.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} upload(key, file, options)
Upload a file stored in CloudMine.
Parameters:
{string} key
The binary file's object key.
{file|string} file
FileAPI: A HTML5 FileAPI File object, Node.js: The filename to upload.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

useApplicationData(state)
Set the application or user-level data mode for this store.
Parameters:
{boolean|undefined} state
If true, this store will only operate in application data. If false, this store will only operate in user-level data. If null/undefined, this store will use user-level data if logged in, application data otherwise.

{APICall} verify(data, options)
Verify if the given login and password is valid.
Parameters:
{object} data
An object with email / username, and password fields.
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.

{APICall} verify(auth, password, options)
Verify if the given email and password is valid.
Parameters:
{string} auth
The email to login
{string} password
The password of the user to login
{object} options Optional
Override defaults set on WebService. See WebService constructor for parameters.
Returns:
{APICall} An APICall instance for the web service request used to attach events.