rise-server-api
This module implements the functionality of the RISE API to the server which allows users to interact with the RISE network via HTTP(S) GET requests.
Installation
Using npm:
npm i rise-server-api
Express is required to run as server, so if Express was not installed yet, also run:
npm i express
Standard setup
If the server hosts a web site (i.e. serves static content, support routes and middleware), you can use the standard setup which will add the RISE interface on top of the existing routes and paths of the web site. In Node.js, the standard way to enhance the Express app looks like:
const RISE = require('rise-server-api')
const rise = new RISE()
app = rise.getExpressAppWithRiseAPI(app)
A complete implementation could look like this:
const express = require('express')
const path = require('path')
const publicPath = path.join(__dirname, 'public')
const port = process.env.PORT || 3000
let app = express()
app.use(express.static(publicPath))
// Now add the RISE API functions to the Express app
const RISE = require('rise-server-api')
const rise = new RISE()
app = rise.getExpressAppWithRiseAPI(app)
// Now add the normal routes and functions to the Express app
app.get('/', (req, res) => {
res.sendFile(path.join(publicPath, 'index.html'))
})
app.get('*', (req, res) => {
res.redirect('/')
})
app.listen(port, () => {
console.log(`Started`)
})
Minimal setup
If the server is only used as an interface to the RISE network, you can skip the standard implementation and write the entire application with just 2 lines of code:
const { app } = new (require('rise-server-api'))({ expressApp: require('express')() })
app.listen(process.env.PORT || 3000)
Testing
In case you do not have a run script ready, add inside package.json the following (assuming index.js is your entry point):
"scripts": {
"start": "node index.js"
}
Run your server with
npm run start
Then use a browser or use curl GET from the terminal and visit the following link (replace localhost:3000 if needed):
localhost:3000/transactions/getUnconfirmedTransactions
You are effectively calling from the RISE API library transactions the function getUnconfirmedTransactions via the server and the default RISE node. The server should now send a request to the default RISE node, which responds with a JSON object (with the property success set to true) that should then be served to you. If you get an error or redirection, something went wrong.
Using the RISE API
By default, most functions from the RISE API libraries accounts, blocks, delegates and transactions are available. Depending on whether the function needs no arguments, single arguments (params) or a query object, HTTP(S) GET requests should be in the form:
directory/apilibrary/function
directory/apilibrary/function/params?param=100
directory/apilibrary/function/query?prop1=abc&prop2=10000&prop3=99999
For example:
localhost:3000/transactions/getUnconfirmedTransactions
localhost:3000/accounts/getBalance/params?address=7889374079483640385R
localhost:3000/transactions/getList/query?limit=50&senderId=7889374079483640385R&and:fromHeight=1318634&and:toHeight=1318834
Basic customization
Basic customization is done by providing the constructor an object with certain settings. Here are the settings with their default values:
const settings = {
// if one has a custom RISE API object (which is unlikely), it can be set here
r = rise,
// set the RISE node's address here
node = 'https://wallet.rise.vision',
// set which API libraries should be available to the outside world
apiLibraries = [ 'accounts', 'blocks', 'delegates', 'transactions' ],
// set which functions from the RISE API should NOT be available; typically, functions that do not provide information should be excluded
excludeFunctions = [ 'enable', 'toggleForging', 'put', 'get' ],
// the base path on which the RISE API functions are available to the outside world, e.g. '/rise/info' sets 'localhost:3000/rise/info/'
basePathName = '',
// by default, if a query property or param fails validation, the request is still send to the RISE node with the remaining valid properties or param
// if false: when a validation fails, no request is send to the RISE node and instead an empty response is returned
alwaysSendQuery = true,
// if set to an Express app, it will enhance that app with the RISE API functionality; primarily used for minimal setups
expressApp = null
}
and then giving this object to the constructor:
// inside a standard setup
const rise = new RISE(settings)
// inside a minimal setup
const { app } = new (require('rise-server-api'))({ ...settings, expressApp: require('express')() })
Advanced customization
Because the constructor returns all functionalities of the module, the module can be customized by changing a property, just like with any other object. For example, the validation rules for the query properties and params are quite loose. One can change a validation function like:
// inside the module's object validateQuery, lives the validation rule for the limit property of a query
// (NOTE: all queries and params entered via HTTP(S) GET requests come in as strings)
validateQuery: {
limit: (nr) => typeof nr === 'string' && nr.match(numbersRegex) !== null
}
// to change the 'limit' validation rule after importing it (for a standard setup):
const rise = new RISE()
rise.validateQuery['limit'] = (nr) => {
return parseInt(nr, 10) && nr.match(/^\d*$/) !== null && parseInt(nr, 10) > 0 && parseInt(nr, 10) <= 500
}
// to change the 'limit' validation rule for a minimal setup:
const { app, validateQuery } = new (require('rise-server-api'))({ expressApp: require('express')() })
validateQuery['limit'] = (nr) => {
return parseInt(nr, 10) && nr.match(/^\d*$/) !== null && parseInt(nr, 10) > 0 && parseInt(nr, 10) <= 500
}