alfa-rest-server

A preconfigured Server for Alfa REST APIs

Install

npm install @alfa-wells/alfa-rest-server --save

Use

Create an Express App

Use the syntax:

RestServer.createApp(<port>, <logger>, [, <allowedOrigins>])

Parameters:

• port: Required. A port number to listen to
• logger: Required. An Alfa-Logger compatible instance
• allowedOrigins: Optional. Default value is "*". Value of the Access-Control-Allow-Origin header used for CORS preflight request.

Example:

const RestServer = require('@alfa-wells/alfa-rest-server')

// You will need a logger
let logger = require('@alfa-wells/alfa-logger')('my-server')

 let app = RestServer.createApp(8080, logger)
 
// Add your routes
app.get('/people/:id', function (req, res) {
		// ...
})

Util

Utilities for REST API coding. Currently:

• Util.getId(<request>[, id-parameter = "id"]): Retrieves the string value of a URL parameter. Throws a bad request ServerError if parameter is not in the URL or if it's not a non-empty string.

const Util = require('@alfa-wells/alfa-rest-server').Util

// ... create your app

app.get('/people/:id', function (req, res) {
	let id = getId(req)
	// Do something with the person id
})


app.get('/reports/:type', function (req, res) {
	let type = getId(req, 'type')
	// Do something with the report type
})

ServerError

Subclass of Javascript Error. Throw a ServerError in your request handlers.

Custom error

Use constructor to create.

new ServerError(<message>[, <status-code>])

Parameters:

• message: A text message or an Error instance.
• status-code: Optional. HTTP status code of the error. Status 500 will be used by default.

Commmon Server Errors

Use static methods to create.

• ServerError.internal(): Creates an HTTP 500 error (Internal Server Error).
• ServerError.badRequest(): Creates an HTTP 400 error (Bad Request).
• ServerError.unauthorized(): Creates an HTTP 401 error (Unauthorized).
• ServerError.forbidden(): Creates an HTTP 403 error (Forbidden).
• ServerError.notFound(): Creates an HTTP 404 error (Not Found).

Example:

const ServerError = require('@alfa-wells/alfa-rest-server').ServerError

// In a request handler
throw ServerError.badRequest()

Methods

Or

If the given error is an instance of ServerError, returns it's argument. Otherwise return this.

serviceError.or(<error>)

Example:

try {
    // some code
} catch (err) {
    // It throws a ServerError. If err is not a ServerError, an internal error is thrown.
    throw ServerError.internal().or(err)
}