Skip to main content

MongoDBStitch

Version: 1.0.0

This library allows your agent code to work with the MongoDB Stitch service.

This version of the library supports the following functionality:

  • Login to MongoDB Stitch using an application API key.
  • Executing a MongoDB Function.

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

To include this library in your project, add

#require "MongoDBStitch.agent.lib.nut:1.0.0"

at the top of your agent code.

Library Usage

Prerequisites

Before using the library you need to have:

Callbacks

All requests that are made to the MongoDB Stitch service occur asynchronously. Every method that sends a request has an optional parameter which takes a callback function that will be executed when the operation is completed, whether successfully or not. The callbacks’ parameters are listed in the corresponding method description, but every callback has at least one parameter, error. If error is null, the operation has been executed successfully. Otherwise, error is an instance of the MongoDBStitchError class and contains the details of the error.

MongoDBStitch Class Usage

Constructor: MongoDBStitch(appId)

Parameter Data Type Required? Description
appId String Yes The Stitch application’s ID

This method returns a new MongoDBStitch instance.

MongoDBStitch Class Methods

loginWithApiKey(apiKey[, callback])

This method logs the agent into to the Stitch application. Authentication is by API key and is required every time the library is restarted.

Parameter Data Type Required? Description
apiKey String Yes The Stitch application’s API key
callback Function Optional Executed once the operation is completed

This method returns nothing. The result of the operation may be obtained via the callback function, which has the following parameters:

Parameter Data Type Description
error MongoDBStitchError Error details, or null if the operation succeeds
response Table The body of the HTTP response received from the MongoDB Stitch service after it has been decoded from JSON into a table. The table’s keys are strings; their values may be any type

executeFunction(name[, args][, callback])

This method executes the specified MongoDB Function. The Function should already exist in the Stitch application.

Parameter Data Type Required? Description
name String Yes The name of the Function
args Array of any type Optional Input parameters for the Function
callback Function Optional Executed once the operation is completed

This method returns nothing. The result of the operation may be obtained via the callback function, which has the following parameters:

Parameter Data Type Description
error MongoDBStitchError Error details, or null if the operation succeeds
response Table The body of the HTTP response received from the MongoDB Stitch service after it has been decoded from JSON into a table. The table’s keys are strings; their values may be any type

setDebug(value)

This method enables (value is true) or disables (value is false) the library debug output (including error logging). It is disabled by default. The method returns nothing.

MongoDBStitchError Class

This class represents an error returned by the library and has the following public properties:

  • type — The error type, which is one of the following MONGO_DB_STITCH_ERROR enum values:
    • MONGO_DB_STITCH_ERROR.LIBRARY_ERROR — The library is wrongly initialized, a method is called with invalid argument(s), or an internal error has occurred. The error details can be found in the details property. Usually this indicates an issue during an application development which should be fixed during debugging and therefore should not occur after the application has been deployed.
    • MONGO_DB_STITCH_ERROR.PUB_SUB_REQUEST_FAILED — An HTTP request to MongoDB Stitch service failed. The error details can be found in the details, httpStatus and httpResponse properties. This error may occur during the normal execution of an application. The application logic should process this error.
    • MONGO_DB_STITCH_ERROR.PUB_SUB_UNEXPECTED_RESPONSE — An unexpected response from the MongoDB Stitch service. The error details can be found in the details and httpResponse properties.
  • details — A string with human readable details of the error.
  • httpStatus — An integer indicating the HTTP status code, or null if type is MONGO_DB_STITCH_ERROR.LIBRARY_ERROR
  • httpResponse — A table of key-value strings holding the response body of the failed request, or null if type is MONGO_DB_STITCH_ERROR.LIBRARY_ERROR.

Examples

Working examples are provided in the Examples.

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version Source Code Notes
1.0.0 GitHub Initial release

License

The MongoDBStitch library is licensed under the MIT License.