taxidromos

Featherlight Node.js/Express module for dispatching API responses. The plan is to build an easy-to-use helper for aligning API responses with these API Design Guidelines

"Taxidromos" is greek for "postman"

Installation

• Install the package via npm

$ npm install taxidromos --save

• Require the module in your app.js (or whatever your main server file is called).

const taxidromos = require("taxidromos")();

Example Usage

Sending HTTP 200 - All Good To Go

Use case: Everything went fine & we should post data to the caller.

• Sends provided data.
• Attaches an HTTP 200 status Code.

app.get('/user', function (request, response) {
   const error = false;
   const data = {
     name: "John",
     lastName: "Doe"
     age: 100
   };

   // `response` is provided by `app.get()`, rest of parameters are up to you.
   taxidromos.postResponse(response, error, data);
});

Sending HTTP 500 - Runtime errors

Use case:

The server threw a runtime error because the request produced a failure that wasn't gracefully handled.

Unless something intervenes to fix this (server restart, maintainance fix) any future requests would be in vain.

• Sends error as is, so you can provide error information on your front-end.
• Attaches an HTTP 500 status Code.

app.get('/user', function (request, response) {
   const error = true;
   const data = null;

   // `response` is provided by `app.get()`, rest of parameters are up to you.
   taxidromos.postResponse(response, error, data);
});

Sending HTTP 400 - Bad Request errors

Use case:

Client has initiated a request that the server crunched but didn't actually enjoy

Use for validation errors, duplicate records etc

• Attaches an HTTP 400 status Code.
• Allows filling-in a payload error.data for use on your front-end
• Note that this is NOT the same data as the regular data we use on succesfull reuqests

app.post('/user', function (request, response) {
  const error = {
    type: "bad-request"
    data: {
      errors: [
        "Customer ID Already Exists",
        "Customer name must contain only alphabetic characters"
      ]
    }
  };

  var data = null;

   // `response` is provided by `app.get()`, rest of parameters are up to you.
   taxidromos.postResponse(response, error, data);
});

Sending HTTP 401 - Unauthorized errors

Use case: Caller login credentials do not authenticate at all (wrong username/password, etc).

• Sends neither error nor data.
• Attaches an HTTP 401 (Unauthorized) status Code.

app.get('/user', function (request, response) {
   const error = { type: "unauthorized" };
   const data = null;

   // `response` is provided by `app.get()`, rest of parameters are up to you.
   taxidromos.postResponse(response, error, data);
});

Sending HTTP 403 - Forbidden errors

Use case: Caller is authenticated (username/password is OK) but this caller doesn't have access to this particular API endpoint.

• Sends neither error nor data.
• Attaches an HTTP 403 (Forbidden) status Code.

app.get('/user', function (request, response) {

   const error = { type: "forbidden" };
   const data = null;

   // `response` is provided by `app.get()`, rest of parameters are up to you.
   taxidromos.postResponse(response, error, data);
});

It's important that your taxidromos calls are within an app.get(req, res). Otherwise there is no request/req to use for responding.

====

API Methods

Posting a response

taxidromos.postResponse(response, error, result)

Posts a response, attaching the appropriate HTTP status code.

Parameters:

| Parameter | Type | Description | |------------|--------------------------------|-----------------------------------------------------------------------------| | response | Object | The response or res as provided by argument from app.get(req, res) | | error | Boolean/Number/String/Object | Use null/false, if there was no error. If there was an error fill the error.type in with the appropriate value. See Example Usage section above for appropriate error.type's you can use'| | result | Object | The actual result you want to send. Stringified internally, so make sure you provide an Object here |

Authors

• Nicholas Kyriakides (@nicholaswmin, [email protected])

License

The MIT License (MIT)

Copyright (c) 2016 Nicholas Kyriakides

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.