response-handler

Response Handler

Cuando se envía el resultado de una petición desde un servicio web, ésta debe incluir suficiente información para que sea interpretado adecuadamente por la aplicación cliente.

Esta librería ofrece un mecanismo simple y flexible que permite dar formato a las respuestas de un servicio web creado con express.

Características

• Es posible definir dos tipos de respuestas success y error.
• El formato de la respuesta es personalizable.
• Se puede configurar para que todas las peticiones sean exitosas (status: 200 Ok).

Tipos de errores

Tipo	Código	Titulo	Mensaje	Causa
BAD_REQUEST	400	Petición incorrecta	Hubo un error al procesar su solicitud, revise el formato en el envío de datos e inténtelo nuevamente.	Ocurre cuando algún dato de entrada no tiene el formato correcto.
UNAUTHORIZED	401	Acceso no autorizado	Debe autenticarse para acceder al recurso.	Ocurre cuando se intenta acceder a un recurso privado.
FORBIDDEN	403	Acceso denegado	No cuenta con los privilegios suficientes para acceder al recurso.	Ocurre cuando se intenta acceder a un recurso privado, utilizando una credencial incorrecta.
NOT_FOUND	404	Recurso no disponible	El servidor no puede encontrar el recurso solicitado.	Ocurre generalmente cuando el registro no existe o ha sido eliminado.
CONFLICT	409	Conflicto	Hubo un error durante el proceso, inténtelo nuevamente.	Ocurre generalmente cuando el registro ha sido modificado y no se puede continuar con el proceso.
PRECONDITION_FAILED	412	Condición insuficiente	No se cumple con algunas condiciones que son necesarias para completar la tarea.	Ocurre cuando no se cumple con ciertas condiciones (validaciones lógicas), por lo general cuando los datos de entrada en conjunto no tienen un sentido lógico.
INVALID_TOKEN	498	Token inválido	El token es inválido	Ocurre generalmente cuando el token ha expirado.
INTERNAL_SERVER	500	Error interno	Hubo un error inesperado, inténtelo mas tarde.	Este error nunca debería ocurrir, generalmente son errores desconocidos que no han sido controlados.

Tipos de respuesta exitosa

Tipo	Código	Titulo	Mensaje	Causa
OK	200	Éxito	La tarea ha sido completada exitosamente.	Ocurre cuando una tarea finaliza correctamente.
CREATED	201	Éxito al crear	El recurso ha sido creado de manera exitosa.	Ocurre cuando una tarea finaliza correctamente y como resultado se ha creado un nuevo recurso.

Función success

Esta función permite crear un middleware que adiciona las propiedades success, success200 y success201 al objeto response de una petición.

Parámetros	Descripción
successHandler	Función que se utiliza para modificar la respuesta antes de que ésta sea tratada.
onSuccess	Función que contiene el resultado final y que puede ser utilizado para realizar otras acciones.
successFormat	Función que da formato al resultado final.

function successHandler (data) {
  return data
}
function onSuccess (result, req) {
  // TODO
}
function successFormat (result) {
  return {
    name     : result.name,
    status   : result.status,
    type     : result.type,
    code     : result.code,
    message  : result.message,
    data     : result.data,
    metadata : result.metadata
  }
}

app.use(Response.success({ successHandler, onSuccess, successFormat }))

Respuestas con el método success200

res.success200({ id: 1, titulo: 'El gato negro' })
res.success200({ id: 1, titulo: 'El gato negro' }, 'Libro obtenido exitosamente.')
res.success200([{ id: 1, titulo: 'El gato negro' }], 'Libro obtenido exitosamente.', { count: 1 })

{
  "name": "ResponseHandlerSuccess",
  "status": "success",
  "type": "OK",
  "code": 200,
  "message": "Libro obtenido exitosamente.",
  "data": [
    {
      "id": 1,
      "titulo": "El gato negro"
    }
  ],
  "metadata": {
    "count": 1
  }
}

Función error

Al igual que con la función success, esta función permite crear un middleware que adiciona las propiedades error, error400, error401, etc. al objeto response de una petición.

Parámetros	Descripción
errorHandler	Función que se utiliza para modificar el error antes de que ésta sea tratada.
onError	Función que contiene el resultado final y que puede ser utilizado para realizar otras acciones.
errorFormat	Función que da formato al resultado final.

function errorHandler (data) {
  return data
}
function onError (result, req) {
  // TODO
}
function errorFormat (result) {
  return {
    name    : result.name,
    status  : result.status,
    type    : result.type,
    code    : result.code,
    message : result.message,
    errors  : result.errors,
    parent  : result.parent
  }
}

app.use(Response.error({ errorHandler, onError, errorFormat }))

Respuestas con el método error400

// Errores producidos desde un controlador
res.error400('msg1')
res.error400({ msg: 'msg1', dev: 'dev1' })
res.error400([{ msg: 'msg1', dev: 'dev1' }, { msg: 'msg2', dev: 'dev2' }])

// Errores producidos desde un midleware
throw new BadRequest('msg1')
throw new BadRequest({ msg: 'msg1', dev: 'dev1' })
throw new BadRequest([{ msg: 'msg1', dev: 'dev1' }, { msg: 'msg2', dev: 'dev2' }])

// Errores producidos desde un controlador de errores
function (err, req, res, next) => {
  err = BadRequest.create('msg1')
  err = BadRequest.create({ msg: 'msg1', dev: 'dev1' })
  err = BadRequest.create([{ msg: 'msg1', dev: 'dev1' }, { msg: 'msg2', dev: 'dev2' }])

  res.error(err)
}

{
  "name": "ResponseHandlerError",
  "status": "error",
  "type": "BAD_REQUEST",
  "code": 400,
  "message": "Petición incorrecta",
  "errors": [
    {
      "msg": "msg1",
      "dev": "dev1"
    },
    {
      "msg": "msg2",
      "dev": "dev2"
    }
  ]
}

Instalación

Para instalar sobre un proyecto, ejecutar el siguiente comando:

$ npm install --save response-handler

Ejemplo

const { Response, errors }   = require('response-handler')
const { PreconditionFailed } = errors
const express    = require('express')
const bodyParser = require('body-parser')

const app = express()
app.use(bodyParser.json())

app.use(Response.success())
app.use(Response.error())

app.post('/libros', (req, res, next) => {
  if (!req.body.titulo) {
    throw new PreconditionFailed('Se requiere el título del libro.')
  }
  res.success200(req.body)
})

app.use((err, req, res, next) => {
  res.error(err)
})

app.listen(4000)

Respuesta exitosa

curl -H "Content-Type: application/json" -X POST -d '{ titulo": "El cuervo" }' http://localhost:4000/libros

{
  "name": "ResponseHandlerSuccess",
  "status": "success",
  "type": "OK",
  "code": 200,
  "message": "Tarea completada exitosamente.",
  "data": {
    "titulo": "El gato negro"
  },
  "metadata": null
}

Respuesta con error

curl -H "Content-Type: application/json" -X POST http://localhost:4000/libros

{
  "name": "ResponseHandlerError",
  "status": "error",
  "type": "PRECONDITION_FAILED",
  "code": 412,
  "message": "Condición insuficiente",
  "errors": [
    {
      "msg": "Se requiere el título del libro.",
      "dev": null
    }
  ]
}