Skip to main content

AlpuraApiResponse – Guía de uso

Este documento explica cómo usar las interfaces de AlpuraApiResponse de la librería de @alpura/core, para poder tener un mayor control y organización con las respuestas que nos proporcionan las APIs.

📁 Importaciones necesarias​

En tu componente local importa IAlpuraApiResponseList y IAlpuraApiResponse usando la librería de @alpura/core.

import { IAlpuraApiResponseList, IAlpuraApiResponse } from "@alpura/core";

🧩 Archivo TypeScript de ejemplo​

export class MyService {
  getRemotesList(
    size = 50,
    offset = 0,
    filter = ""
  ): Observable<IAlpuraApiResponseList<IRemoto>> {
    const params = AlpuraHttpParams.buildHttpParams({ size, offset, filter });
    return this.http
      .get<IAlpuraApiResponseList<IRemoto>>(url, {
        params,
      })
      .pipe(AlpuraApiError.handleApiError());
  }

  createRemote(
    payload: IRemotePayload
  ): Observable<IAlpuraApiResponse<IRemoto>> {
    return this.http
      .post<IAlpuraApiResponse<IRemoto>>(url, payload)
      .pipe(AlpuraApiError.handleApiError());
  }
}

Las interfaces IAlpuraApiResponseList y IAlpuraApiResponse nos permiten acceder a la estructura base de la respuesta de la API que incluye datos genéricos.

A continuación se describen:

/**
 * Estructura para respuestas que devuelven una lista de objetos con paginación opcional.
 * @template T Tipo de dato contenido en la lista.
 */
export interface IAlpuraApiResponseList<T> extends IAlpuraBaseApiResponse<T[]> {
  totalRows?: number;
  page?: number;
}

/**
 * Tipo alias para respuestas que devuelven un único objeto.
 * @template T Tipo de dato esperado.
 */
export type IAlpuraApiResponse<T> = IAlpuraBaseApiResponse<T>;

/**
 * Estructura base para la respuesta de la API que incluye datos genéricos.
 * @template T Tipo de dato esperado en la propiedad data.
 */
export interface IAlpuraBaseApiResponse<T> {
  /** Información del encabezado de la respuesta. */
  header: IAlpuraResponseHeader;
  /** Indicador de éxito de la operación. */
  success: boolean;
  /** Lista de errores retornados por la API, si existen. */
  errors: IAlpuraApiError[];
  /** Datos devueltos por la API. */
  data: T;
  /** Token actualizado para autenticación o sesión. */
  newToken: string;
}

/**
 * Información del encabezado de la respuesta de la API.
 */
export interface IAlpuraResponseHeader {
  /** Código numérico de la respuesta. */
  code: number;
  /** Mensaje principal descriptivo de la respuesta. */
  message: string;
  /** Detalle adicional sobre la respuesta. */
  detail: string;
}

/**
 * Representa un error específico retornado por la API.
 */
export interface IAlpuraApiError {
  /** Código identificador del error. */
  code: string;
  /** Clave o campo relacionado con el error. */
  key: string;
  /** Mensaje descriptivo del error. */
  message: string;
}

🚀 Resultado esperado​

Con la correcta implementación de estas Interfaces, el desarrollador podra acceder de manera correcta a la respuesta de las invocaciones de las APIs.

📬 Soporte​

Para dudas o mejoras. contactar al equipo de arquitectura.