Al trabajar en un entorno con varios equipos de desarrollo, cada uno dedicado a desarrollar o mantener distintas partes de un producto o sistemas de una compañía, la comunicación es uno de los problemas más comunes que se suelen encontrar.

Para evitar adaptarse a distintas APIs dependiendo de la aplicación y facilitar el desarrollo, existen estándares para definir el formato de las respuestas como JSend.

JSend es un estándar de respuesta para la comunicación entre aplicaciones, basado en un JSON con la siguiente forma:

{
	"status": "SUCCESS",
	"data": {
		"user": {
			"username": "username",
			"email": "username@domain.com",
			...
		}
	}
}

Status

Representa el estado final de la acción, que puede ser:

• SUCCESS
  • La acción que requería la petición se ha llegado a completar correctamente.
• FAIL
  • Las precondiciones para la acción requerida no se han cumplido.
  • Error por parte del cliente (HTTP 4xx).
• ERROR
  • Se ha producido un error procesando la acción requerida.
  • Error por parte del servidor (HTTP 5xx).

Data

Contiene información extra sobre el resultado de la acción ejecutada. Su contenido puede cambiar en función del status:

• SUCCESS

  • El contenido será el recurso que se había pedido recuperar o un objeto vacío en caso de que la acción no tuviera nada que devolver:

    {
    	"status": "SUCCESS",
    	"data": {}
    }

• FAIL

  • Puede plantearse de varias formas, pero lo importante es especificar la precondición (o precondiciones) que no se han cumplido, para que el cliente pueda corregirlas.

  • Normalmente se añade un código para identificar el error y un mensaje que da más información. Se pueden declarar los campos como tal o tomarlo directamente como un objeto clave-valor donde la clave sea el código y el valor la descripción:

    // Versión estructurada
    {
    	"status": "FAIL",
    	"data": {
    		"code": "InvalidEmailFormat",
    		"message": "Email address 'user@domain' has an invalid format"
    	}
    }
    // Versión clave-valor
    {
    	"status": "FAIL",
    	"data": {
    		"InvalidEmailFormat": "Email address 'user@domain' has an invalid format"
    	}
    }

• ERROR

  • Aunque puede plantearse de la misma forma que los FAIL, también existe la opción de prescindir del campo data y asumir que, al ser un error por parte del servidor, no hace falta especificar más allá de un mensaje descriptivo:

    // Versión con campo "data"
    {
    	"status": "ERROR",
    	"data": {
    		"code": "UnexpectedError",
    		"message": "Unexpected network error occurred"
    	}
    }
    // Versión simplificada
    {
    	"status": "ERROR",
    	"message": "Unexpected network error occurred"
    }

Consideraciones

No existe una forma única de hacer las cosas y cada contexto es diferente, por lo que antes de aplicarlo es importante comentarlo con el resto y llevarlo a los acuerdos de equipo adaptándolo a las necesidades que existan. Por ejemplo, podría considerarse redundante especificar códigos de error si la API que se va a consumir solo gestiona un número limitado de errores, pudiendo solamente fijarse en el código HTTP de respuesta.

Aunque está bien tener un estándar, no hay que perder de vista que es simplemente eso, una base de la que partir. .