Respuestas de API

El modelo de respuesta del API agrupa los errores en categorías, adoptando el modelo de respuestas HTTP como códigos de cada grupo. Se adoptan sólo una seríe de códigos HTTP para reflejar el resultado de la operación, además, las respuestas incluyen descripción de los errores y en algunos casos el detalle del origen del error en el campo data.

Las respuestas que sean ejecutadas de manera correcta, regresarán un código HTTP 200.

Códigos de error HTTP

Procesamiento de errores

Cuando un error se presenta, en el cuerpo del mensaje estará presente un objeto error. El contenido del objeto informará el tipo de error que se presentó, así como una breve descripción. En algunos casos, el error proveerá información adicional que facilitará el proceso de debug, todo detalle adicional estará contenido en el campo data.

Ejemplo de error:

{
  "status": "error",
  "error": {
    "code": 429,
    "type": "Sistema",
    "message": "Ha excedido la tasa máxima de peticiones"
  },
  "http_code": 429,
  "datetime": "2018-09-05T15:30:49-05:00",
  "timestamp": 1536179449
}

Ejemplo de error 400 con detalle en data:

{
  "status": "fail",
  "error": {
    "code": 400,
    "type": "Parámetros",
    "message": "Error en parámetros de entrada."
  },
  "http_code": 400,
  "datetime": "2018-09-06T13:33:33-05:00",
  "timestamp": 1536258813,
  "data": {
    "errors": {
      "email": [
        "El campo email no corresponde con una dirección de e-mail válida."
      ]
    }
  }
}

Eliminar un objeto

Cuando sea eliminado un objeto se recibirá un código HTTP 200 y en el cuerpo del mensaje se indicará el detalle del objeto eliminado y la hora a la que se ejecutó el proceso.

Ejemplo de respuesta:

{
  "status": "success",
  "http_code": 200,
  "datetime": "2018-09-06T00:53:01.404Z",
  "timestamp": 0,
  "data": {
    "tarjeta": {
      "token": "string",
      "eliminacion": "2018-09-06T00:53:01.404Z"
    }
  }
}

Wrapper de Respuestas de API

En general, todas las respuestas del API incluyen un wrapper en las respuestas, el concepto detrás del wrapper es permitir una rápida interpretación de la ejecución de la petición realizada, más no del resultado, el resultado estará contenido en el campo data, algunas peticiones también podrán incluir un objeto error en el cuerpo del mensaje.

Ejemplo del wrapper:

{
  "status": "success",
  "data": {},
  "http_code": 200,
  "datetime": "2018-08-30T10:58:21-05:00",
  "timestamp": 1535644701
}

Los campos que contendrá el wrapper son descritos a continuación.

Status

El valor de "status" podrá contar con cualquiera de los siguientes valores:

1. success - indicará que la petición fue al API fue procesada correctamente. El detalle de la operación solicitada se encontrará en el campo data.
2. fail - indicará que hubo un error con los valores enviados en la petición o no se cumplió con una precondición, por ejemplo no se incluyó un vampo obligatorio.
3. error - indicará que ha ocurrido un error al procesar la petición, por ejemplo, que ha sucedido una excepción al procesar la operación.

http_code

Contendrá siempre el mismo valor del código HTTP en encabezados.

Data

Contendrá el cuerpo (datos) de la respuesta. Hay respuestas del API que no incluirán datos en el campo.