Federation-Response (FR)

The Federation Response module is a predefined response structure that is used by APIs in the API-Federation Ecosystem (AFE) to serve responses that conform to the R1-Response structure as defined by AFE.

Introduction

1. Getting Started

Lets complete the stepts in the list below to get us started:

• require in your store.js file as storefile.
• run $ npm install federation-response in your project directory.
• require Response from federation-response.
• pass in the storefile as an argument to Response and new to create a new Response instance. The code below illustrates the steps above:

const storefile = require('./store.json')
const { Response } = require('federation-response')

const fres = new Response(storefile)
    .payloadTo({user:{id:1}, roles:[1,2,3]})
    .message('invalid_password')
    .done()

console.log(fres)

The code above would yield teh response below:

Response {
  id: 7395,
  isFederationResponse: true,
  status: null,
  lang: 'en',
  payload: { user: { id: 1 }, roles: [ 1, 2, 3 ] },
  details: [
    {
      code: 'invalid_password',
      status: 422,
      state: 'validation',
      key: 'password',
      message: 'the password you entered is invalid'
    }
  ],
  directives: [],
  created: '3/11/2020, 2:12:26 PM'
}

API Documentation

In this section, we will demonstrate how to use this module. for the remainder of this section, we will assume that fres has already been instantiated as illustrated below.

const storefile = require('./store.json')
const { Response } = require('federation-response')

const fres = new Response(storefile)

1. Payload

- payloadTo()

The payloadTo(any) method takes in one argument of type any. The payloadTo method is used to set the payload attribute of your fres object. Note: if this method is called more than once on the fres instance, previously loaded payload data will be overwritten.

    const data = [
        { id: 1, usernmae:'some-username'}
        { id: 2, usernmae:'some-other-username'}
    ]
    fres.payloadTo(data) 

2. Messages

- message()

The message(string, object) method takes in two arguments. The first is of type string and the second is an optional object. The first argument string should match a notification key in your store file if a match can't be found it will add a default error to details. The second parameter should only be provided if the corresponding notification is a template notification. Template notifications include placeholder words that are denoted by words enclosed by curly braces preceded by a dollar sign like so: ${this-is-a-key-word}. If the data object contains an object with property names matching the keywords, the keywords will be replaced by the matching values in the data object.

Let us consider the example below to help us better understand the conditions explained above. For this example we will assume the following:

• storefile contains two notifications:
• happy_birthday
• authenticated_user
• happy_birthday is a template notification, which means that it contains replaceable keywords.

Here are the two notification strings represented before they are renderd:

    let happy_birthday = 'happy ${age}th birthday ${name}!'
    let authenticated_user = 'welcome back!'

General notification example:

    fres.message('authenticated_user') // outputs - 'welcome back!'

Template notification example:

    const data = { name: 'some-username', age: 18}
    fres.message('happy_birthday', data) // outputs - 'happy 18th birthday some-username!'

- messageTo()

The messageTo method allows you to add a custom unstructured message to the details property. It is advisable to use the same message format as the auto-generated messages to ensure that clients will be able to process your data correctly.

    fres.message({
        state: 'some-custom-notification-name',  
        status: 200,
        state: 'error',
        key: 'some-username', 
        message: 'some-username', 
    }) 

3. Directives

- directiveTo()

Directives are the server's way of telling a client to do something. To illustrate the relevance of this, let us consider a malicious client that tries to access a user's data by providing a tampered JWT. If we detect that the signature is invalid we can send instructions to the client to clear local storage or make an entry in local storage to block this client from retrying. Node: directives are just text send along with the response, it is up to the front-end developer to write logic to handle them. Directives are added to the directives array be the directiveTo(string) method.

    fres.directiveTo('directive_name') 

4. State Mutation Methods

- statusTo()

Sets the status of the response to the provided integer.

- langTo()

Sets the language of the response to the provided language if it is in the applications project scope, otherwise, it defaults to English.

- isSilent()

This indicates to the client that this message should not be displayed to the user.

- done()

Makes the request ready to be dispatched by removing operational content.

- throw()

Throws an error with the content of the object.

5. Some More Examples

const storefile = require('./store.json')
const { Response } = require('federation-response')

const fres = new Response(storefile)

let fres = new Response(store)
    .payloadTo({user:{id:1}, roles:[1,2,3]})
    .message('invalid_password')
    .message('authenticated_user')
    .message('authenticated_user', {username: 'some-cool-name'})
    .message({first:'custom message'})
    .messageTo({message:'this is a custom message'})
    .done()

The code above would yield teh response below:

Response {
  id: 3033,
  isFederationResponse: true,
  status: null,
  lang: 'en',
  payload: { user: { id: 1 }, roles: [ 1, 2, 3 ] },
  details: [
    {
      code: 'invalid_password',
      status: 422,
      state: 'validation',
      key: 'password',
      message: 'the password you entered is invalid'
    },
    {
      code: 'authenticated_user',
      status: 200,
      state: 'info',
      key: '',
      message: 'welcome back ${username}!'
    },
    {
      code: 'authenticated_user',
      status: 200,
      state: 'info',
      key: '',
      message: 'welcome back some-cool-name!'
    },
    {
      code: 'invalid_message_code',
      status: 500,
      state: 'error',
      key: '',
      message: 'the message code you provided could not be found. - 3033'
    },
    { message: 'this is a custom message' }
  ],
  directives: [],
  created: '3/11/2020, 4:16:05 PM'
}