1Life Endpoint Utils

A JavaScript package which contains utilities, pertaining to endpoints, common among 1Life WebCore services.

Getting Started

1. Connect to the WebCorePackages feed.

2. Generate or refresh your VSTS token.

3. Run npm install 1life-endpoint-utils.

4. Import and use the exposed classes to validate your endpoints.

Connecting to the WebCorePackages feed

To connect to the WebCorePackages feed you need to create a .npmrc file in your project's root folder (the folder containing the package.json).

The .npmrc file should contain the following code:

registry=https://pkgs.dev.azure.com/Telesure/1Life/_packaging/WebCorePackages/npm/registry/

always-auth=true

Generate or refresh your VSTS token

This package is protected using Visual Studio Team Services (VSTS) and will require you to have a valid VSTS token

If you haven't used Azure Artifacts with npm you will need to do the following:

1. Install node and npm.
2. Install vsts auth for npm with the following command: npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false
3. Retrieve a vsts token by running the following command: npm run refreshVSToken

If you already have used packages in the WebCorePackages feed you might need to refresh your VSTS token. You can do so by running:

npm run refreshVSToken

Usage

This package currently contains utilities to:

• Validate an endpoint

Validate an endpoint

To validate an endpoint, start by importing the EndpointValidator and ValidatableParameter classes.

const { ValidatableParameter, EndpointValidator} = require('1life-endpoint-utils')

Define all the required parameters for your endpoint:

const requiredParameters = [
    new ValidatableParameter('name', true),
    new ValidatableParameter('description', true),
    // Validation can be nested
    new ValidatableParameter('language', true, [
        new ValidatableParameter('code', true),
        new ValidatableParameter('name', true)
    ])
]

To determine if an endpoint is valid, do the following:

const endpointIsValid = EndpointValidator.determineEndpointHasValidParameters(request.body, requiredParameters)

To provide an error message informing the endpoint consumer which field is missing, do the following:

const validationErrorMessage = EndpointValidator.determineEndpointMissingParameterMessage('body', request.body, requiredParameters)
response.status(400).send(validationErrorMessage)

Here is a (somewhat) full, Express implementation of validating an endpoint.

const { ValidatableParameter, EndpointValidator} = require('1life-endpoint-utils')

//
// Define routes
//

function addBook(request, response) {
    const requiredParameters = [
        new ValidatableParameter('name', true),
        new ValidatableParameter('description', true),
        // Validation can be nested
        new ValidatableParameter('language', true, [
            new ValidatableParameter('code', true),
            new ValidatableParameter('name', true)
        ])
    ]

    if (!EndpointValidator.determineEndpointHasValidParameters(request.body, requiredParameters)) {
        const validationErrorMessage = EndpointValidator.determineEndpointMissingParameterMessage('body', request.body, requiredParameters)
        response.status(400).send(validationErrorMessage)
    }

    //
    // Rest of the endpoint logic
    //
}

API Reference

Models

ValidatableParameter

A parameter on an endpoint which can be validated.

A parameter on an endpoint can come from the query, params or body of the request.

Currently, only supports validation to check if the parameter is present, type validation is not yet supported.

source code

Fields

• name: String field name of the validatable parameter

• checkTruthiness: boolean Determines if a truthiness check must be done. If true then the parameter cannot be an empty string, zero, an empty array or undefined. If false the parameter cannot be undefined but can be an empty string, zero or an empty array.

• requiredFields: ValidatableParameter[ ] If the parameter is an object, use this field to declare the required fields of the object so that they too may be validated

Classes

EndpointValidator

Contains logic pertaining to the validation of (request data on) endpoints

source code

Methods

• determineEndpointHasValidParameters(parameters, requiredParams): boolean Determines if the supplied parameters are valid. @parameters: any[] - The parameters of the endpoint, can be from the request query, params or body. @requiredParams: ValidatableParameter[ ] - The required parameters of the endpoint.

• determineEndpointMissingParameterMessage(parentObjectName, parameters, requiredParams): String Provides an error message for the missing parameter. @parentObjectName: String - The name of the parent object of the supplied parameters, typically query or body. @parameters: any[] - The parameters of the endpoint, can be from the request query, params or body. @requiredParams: ValidatableParameter[ ] - The required parameters of the endpoint.