Skip to content

API Reference

Jump to bottom
Henri Normak edited this page Feb 18, 2016 · 6 revisions

API Reference

The following page lists the entire public API of lambda-foundation.

Table of Contents

Authentication

authenticate(token, requirements)

Main authentication function, which takes a JWT token (HTTP Authorization header contents also works) and an optional set of requirements that the token has to satisfy. The function returns a promise, which either resolves into a decoded JWT token or rejects with an appropriate error (HTTP codes 401 if invalid token, or 403 if requirements not satisfied).

Parameters
  • token - Encoded/Signed JWT token (Bearer prefix is stripped)
  • requirements - object describing the requirements, currently valid keys to use are:
    • rule - A constant from the RULE property on the authentication module (ANY, NONE, ALL), signifies which of the scopes the token has to have
    • scope - An array/Single scope that the token has to fulfil based on the rule (authentication exposes constants in the SCOPE property - TESTER, CLIENT, QA, ADMIN)

isAuthorized(token, requirements)

Helper function for checking a decoded JWT token against requirements. Returns either true or false.

Parameters
  • token - Decoded JWT token
  • requirements - object describing the requirements, currently valid keys to use are:
    • rule - A constant from the RULE property on the authentication module (ANY, NONE, ALL), signifies which of the scopes the token has to have
    • scope - An array/Single scope that the token has to fulfil based on the rule (authentication exposes constants in the SCOPE property - TESTER, CLIENT, QA, ADMIN)

isValidToken(token)

Helper function for validating the signature of an encoded JWT token and decoding the contents. Returns the decoded JWT token, throws an error if one occurs (for example the signature of the token is invalid).

Parameters
  • token - Encoded JWT token

Configuration

Configuration module exports the resolved configuration as an object. The result has no public functions, but does always include some values. Rest of the values are loaded from the microservice configuration directory - defaults to /config in project root. The logic for loading configuration files is as follows: default.json is always loaded, <NODE_ENV>.json is loaded based on the NODE_ENV of the process and finally environment variables are mapped to configuration values as described in custom-environment-variables.json. The results of these steps are merged (in the given order) and the results are exposed as the configuration submodule.

project

Information about the microservice project, which is picked up from the environment during deployment.

  • name - name of the project

aws

Information about the AWS environment the microservice has been deployed to/is running in. This information is picked up during deployment from the environment.

  • stage - Name of the stage that the service has been deployed to, something like dev or prod
  • region - AWS availability region that the service has been deployed to, something like us-east-1

Discovery

Similarly to the configuration submodule, the discovery submodule also exports the resolved resources as an object that offers as a key-value store, having no public functions. The resources are loaded from the discovery.json file in the project root. The structure of the file is as follows, at the top level there is a resources key, that contains key-value pairs of resources for the service. Resources can be nested. Furthermore, if a resource sets its passthrough flag to true, then only its child resources are resolved.

Base URL for the resources is taken from configuration, under the url.base keypath.

An example:

{
    "resources": {
        "example": {
        },
        "nested-example": {
            "resources": {
                "foo" : {}
            }
        },
        "passthrough-example": {
            "passthrough": true,
            "resources": {
                "bar": {}
            }
        }
    }
}

Results in resolved resources (omitting the base of the HREFs):

{
    "resources": {
        "example": {
            "href": "/example"
        },
        "nested-example": {
            "href": "/nested-example",
            "foo": {
                "href": "/nested-example/foo"
            }
        },
        "passthrough-example": {
            "bar": {
                "href": "/passthrough-example/bar"
            }
        }
    }
}

Error

config(options)

Alter the configuration of error reporting. Currently allows updating the Raygun API key that is used, as well as the tags that should always be included.

Parameters
  • options - Object containing new configuration options, currently supported keys:
    • tags - Array of default tags that should always be sent along with any error report
    • apiKey - Raygun API key to use when reporting the error

error(code, message, extra, request)

Create a new error. Returns the created error.

Parameters
  • code - Code for the error (for example HTTP status code)
  • message - Error message
  • extra - Additional metadata that is sent when reporting the error
  • request - Optional request information that should be reported along with the error

report(error, additionalTags)

Report an error to the backend. Currently sends errors to Raygun. Returns a promise, that resolves to the same error that was passed in.

Parameters
  • error - error object that should be reported
  • additionalTags - array of additional tags to add to the report, complements the list set via config.
Clone this wiki locally