fh-mbaas-express
fh-mbaas-express is the FeedHenry MBaaS running on top of Express.
Project Info | |
---|---|
License: | Apache License, Version 2.0 |
Build: | npm |
Documentation: | http://docs.feedhenry.com/v3/api/cloud_api.html |
Issue tracker: | https://issues.jboss.org/projects/FH/summary |
Mailing list: | feedhenry-dev (subscribe) |
IRC: | #feedhenry channel in the freenode network. |
Usage
Add the following to the 'dependencies' section of the app's 'package.json' file:
"fh-mbaas-express" : "~5.6.1",
"express" : "~4.14.0"
Add a file to the app's 'application.js', with the following contents:
var express = ;var mbaasExpress = ;var cors = ; // list the endpoints which you want to make securable herevar securableEndpoints;// fhlint-begin: securable-endpointssecurableEndpoints = '/hello';// fhlint-end var app = ; // Enable CORS for all requestsapp; // Note: the order which we add middleware to Express here is important!app;app; // Note: important that this is added just before your own Routesapp; // allow serving of static files from the public directoryapp; // fhlint-begin: custom-routesapp;// fhlint-end // Important that this is last!app; var port = processenvFH_PORT || processenvVCAP_APP_PORT || 8001;var server = app;
When running on the FeedHenry platform, this module should not be used directly. Instead, fh-mbaas-api module should be used and an instance of fh-mbaas-express cab be obtained via fh-mbaas-api. E.g.
var mbaasApi = ;var mbaasExpress = mbaasApi;
Customising & Extending
The above application.js is just an Expressjs application - it's easily extensible.
Custom APIs
You can create custom API handlers in the Express format by doing:
app.use('/myapi', function(req, res){
res.end('My custom response');
});
See Express Router for more information.
Serving Static Files
Express has a built-in static file server. In this example, we host files under the public directory:
app.use(express.static(__dirname + '/public'));
REST API
Cloud
(POST | GET | PUT | DELETE) /:someFunction
Authentication : Optional - can be enabled globally or on a per-endpoint basis under "Endpoints" section of the studio. Response formats : JSON, binary, plain text
Headers
x-fh-auth-app : API key of your application, found under the "details" section of the studio.
Body:
JSON format - paramaters to be passed to the exported function, see 'Writing API Functions'.
Response:
Result as passed to the callback function of the exported function - see 'Writing API Functions'.
Writing API functions
See Express Router for more information.
{ var hello = ; hello; // GET REST endpoint - query params may or may not be populated hello; return hello;}
mBaaS
POST /mbaas/db
Authentication : Required - App API key goes here. Response format : JSON
Headers
x-fh-auth-app : API key of your application, found under the "details" section of the studio.
POST Body:
JSON body - same as $fh.db params. A summary of body options follows - For more, see $fh.db docs
{
"act": "create|update|list|delete|deleteall",
"type": "collectionName",
"guid": "GUID of object operating on - not required for list or deleteall",
"fields": "JSON definition of fields - required for create|update",
"eq|ne|in" : "JSON definition of query to match - supported for list only"
}
Response:
As per $fh.db
Sys
GET /sys/info/ping
Authentication : None Response formats : Plaintext
Headers
None
Response:
"OK"
if application is running as expected. Will respond with a 404 otherwise
GET /sys/info/endpoints
Authentication : None Response formats : JSON
Headers
None
Response:
{
endpoints : ['array of endpoints exported as public functions']
}
GET /sys/info/memory
Authentication : None Response formats : JSON
Headers
None
Response:
{
rss: 13721600, // Resident set size
heapTotal: 7195904, // V8's total available memory
heapUsed: 2369744 // V8's used memory
}
GET /sys/info/memory
Authentication : None Response formats : Plaintext
Headers
None
Response:
0.1.0
Backward compatability with main.js
If you want to use the older fh-nodeapp/fh-webapp style main.js, you need to change the /cloud endpoint in your application.js as follows:
var mainjs = require('./lib/main.js');
app.use('/cloud', mbaas.cloud(mainjs));
Additionally, you need to ammend the call to sys
for secure endpoints:
app.use('/sys', mbaas.sys(securableEndpoints, mainjs));