npm package "ms-api-request"

Introduction

This package is used by Me Salva Engineering Team to make requests to Api, using HMAC authentication protocol + universal fetch to make requests by server side (we use express) + Json Api Serializer to parse the api JSON API BASED to simple Javascript Camel Case Based objects

Installation

yarn way

yarn add ms-api-request

npm way

npm install --save ms-api-request

Configurations

.env file

On project root folder add a file called .env.js with the structure below:

module.exports = {
  API_HOST: 'https://API_HOST',
  CLIENT: 'WEB|ANDROID|IOS|...',
  HMAC_KEY: 'HMAC_KEY',
  CREDENTIALS_COOKIE_NAME: 'user-credentials|admin-credentials|...',
}

Express middleware

To work on server side, you need to add this express middleware:

const express = require('express');
const msApiRequestMiddleware = require('ms-api-request/middleware');
const server = express();

server
  .use(...other_middlewares)
  .use(msApiRequestMiddleware())
  .get(...ROUTES)
  .listen(PORT)

Usage

Creating a model

./examples/ExampleModelA.js

import MSApiRequest from 'ms-api-request'

const ExampleA = new MSApiRequest('some_api_route')

export default ExampleA

This model allow you to use the methods below:

./examples/ExampleUsage1.js

import Example1 from './examples/ExampleModelA'

Example1.request({
  method: 'GET|POST|PUT|DELETE|PATCH', //default = GET
  route: 'additional route', //default = GET
  data: {...OBJECT_WITH_REQUEST_PARAMS}, //default = undefined
  headers: {...OBJECT_WITH_ADDICTIONAL_HEADERS}, // default = undefined
  only: 'data|headers|status|meta', // default = undefined
}).then(response => {
  console.log(response.data)
  console.log(response.meta)
  console.log(response.headers)
  console.log(response.status)
})

Custom ENVS

You can pass some custom env vars on MsApiRequest initialization. This will allow to use two or more api accesses in the same project.

import MSApiRequest from 'ms-api-request'

const ExampleA = new MSApiRequest('some_api_route', {
  API_HOST: 'https://some.another.host',
  HMAC_KEY: 'SomeAnotherHmacKey'
})

export default ExampleA

Some alias

./examples/ExampleUsage2.js

import Example2 from './examples/ExampleModelA'

Example2.get().then(data => console.log(data))
// will make a GET request to: https://api_host/some_api_route

// is the same that:
Example2.request({ method: 'GET', only: 'data' }).then(data => console.log(data))
// or the same that:
Example2.request({ method: 'GET' }).then(response => console.log(response.data))


Example2.post({ data: {someField: 'someValue'}}).then(data => console.log(data))
// is the same that:
Example2.request({
  method: 'POST',
  only: 'data',
  data: {someField: 'someValue'},
}).then(data => console.log(data))
// will make a POST request to: https://api_host/some_api_route, sending as payload  {"someField": "someValue'}

These are the valid alias: [ post, put, delete, get, patch ]

Explaining request params

• method - Set request HTTP method, the allow methods are: GET, POST, PUT, PATCH, DELETE.

• data - For GET method, means that will add as a url query string params, to other methods send as payload in JSON hyphen-saparated format

• headers - add headers to request. This lib will automatic add the headers below, so, this headers can't be overflowed.

  • X-DATE - Some enviroments don't allow to send DATE header, so we send this header by security

  • CLIENT - the same client provided on .env.js file

  • CONTENT-TYPE - application/json

  • PLATFORM - Send to api which platform is requesting

  • DEVICE - Send to api which device is requesting

  • USER-AGENT - Send to api the user-agent of the device that is requesting

  • CONTENT-MD5 - Encrypted data, using HMAC KEY

  • AUTHORIZATION - HMAC authentication protocol implementation created using the canonical string composed by: method + content type + Content-MD5 + pathname + date

  • UID - user authenticated uid (if is not guest user)

  • ACCESS-TOKEN - user authenticated access-token (if is not guest user)

Code Quality

The project have 100% test coverage and no lint issues! All master interactions must have the same code quality