Custom REST routes in restdb.io lets you create new API endpoints with serverless Javascript functions. You can create a route API endpoint to serve any content, e.g. JSON, HTML, XML, etc.
Note that you can also achieve similar functionality using Page codehooks.
Custom routes are served under the /views/subroute of your database endpoint. E.g.
https://mydb-f1e0.restdb.io/views/myroute
or the same route under a custom secure domain.
https://example.com/myroute
The Hello world serverless Javascript as a custom GET /myroute:
// #!/javascript
const onGET = (req, res) => {
res.end({"text": "Hello world!"});
}
Custom routes and APIs provides your data backend with more power and flexibility.
Custom REST routes are implemented as Pages. If you are familiar with this concept, you're good to go, otherwise check the docs here.
In developer mode, click the Pages/views + link. Enter the route and a description for the new page. Optionally add an icon.
After saving the new Page, you can review the setting where you can see the full URL route and some other Page settings.
Note that the Name for the route must start with a /, e.g.
/myroute. Route parameters can also be applied with/myroute/:param1/:param2
Clicking on the code editor in the left menu opens the code editor.
The first line is important to indicate that the code contains a custom route with Javascript. The canonical format for a custom route Javascript is:
// #!/javascript
// replace onXXX with onGET, onPOST, onPUT, onPATCH, onDELETE
const onXXX = (req, res) => {
...
}
The example below shows the mandatory Hello world! version for a custom route in restdb.io.
Clicking on the preview menu item, opens a new browser window and renders the output.
Custom routes have the same security rules as all REST API calls. Create api keys or use JWT to authenticate against the API.
Warning: If you set the Page to public, all security is off, and you will need to handle access in your code through HTTP headers and status code.
Read more here: https://restdb.io/docs/apikeys-and-cors
Custom REST routes are implemented as Javascript Codehooks. They share the same APIs and utility functions as any other Codehook.
For a custom route to respond to a REST verb, the corresponding method of the REST verb must be implemented as a Javascript function.
onGET(req, res)
onPOST(req, res)
onPUT(req, res)
onPATCH(req, res)
onDELETE(req, res)
The request parameter has the following properties:
The response parameter ends the request and sends back the output and header values from the code. Allowed properties are status, text, json and headers. Status is default 200. In the example below, we return a 401 status code unless the param is correct (note that this example is not to be used for security purposes - use a JSON Web token approach instead).
// #!/javascript
// serve GET requests with secret param, e.g. https://mydb-fe00.restdb.io/views/theroute?secret=4321
const onGET = (req, res) => {
const password = '4321';
const secret = req.params && req.params['secret'] || '';
if (secret !== password) {
res.end({status: 401, json: {message: "Stay away!"}});
} else {
res.end({
status: 200,
json: {someval: "Hello world!"},
});
}
}
You can send plain text or JSON objects.
res.end(
{
text: "<h1>Hello world!</h1>",
headers: {"content-type": "text/html"}
}
)
res.end(
{
json: {
"msg": "Hello world!",
"count": 42
}
}
)
A custom route that runs a database query and manipulates the result.
// #!/javascript
/*
Run route as a function
*/
const onGET = (req, res) => {
db.get("/rest/company", {}, {$max: 10}, (dberr, dbdata) => {
log.debug("Input", req);
const json = dbdata.map( (el) => {
return {name: el.name, letters: el.name.length}
});
json[0] = {"First record is special": "now! "+ new Date()};
log.info("Got some data here", req, json);
res.end({json: json});
})
}
Example JSON output:
[
{
"First record is special": "now! Sun Apr 15 2018 11:15:27 GMT-0400 (EDT)"
},
{
"name": "Pfeffer Inc",
"letters": 11
},
{
"name": "Zboncak LLC",
"letters": 11
},
{
"name": "Bergstrom PLC",
"letters": 13
}
]
