Principio de Diseño de APIS - ReinelPuentes92/ArquitectDDD GitHub Wiki

Principios de Diseño de APIS

  1. Las API REST se diseñan en funcion de los recursos (Cualquier tipo de objeto, datos o servicio a los que el cliente puede acceder).
  2. Un recurso tiene un identificador, que es la URI que identifica de forma unica al recurso.
  3. Los clientes interactuan con el servicio intercambiando representaciones de recursos (JSON como formato de intercambio).
  4. Las API REST utilizan un modelo de solicitud sin estado. Las Solicitudes HTTP deben ser independientes y pueden ocurrir en cualquier orden, por lo que no es factible mantener informacion de estado transitoria entre solicitudes.

Tipos de Retorno de Acciones del Controlador

  1. Specific Type: Las acciones o metodos del controlador, de vuelven un tipo primitivo y complejo.
  2. IAction Result: Son usados cuando se utilizan multiples tipo de retorno en una accion.
  3. ActionResult: Permite retornar un tipo de dato especifico

Metricas calidad de codigo

  1. Índice de mantenimiento: calcula un valor de índice entre 0 y 100 que representa la facilidad relativa de mantener el código. Un valor alto significa una mejor capacidad de mantenimiento. Las clasificaciones codificadas por colores se pueden usar para identificar rápidamente puntos problemáticos en el código. Una clasificación verde está entre 20 y 100 e indica que el código tiene buena capacidad de mantenimiento. Una clasificación amarilla está entre 10 y 19 e indica que el código se puede mantener moderadamente. Una clasificación roja es una clasificación entre 0 y 9 e indica una baja capacidad de mantenimiento.
  2. Complejidad ciclomática: mide la complejidad estructural del código. Se crea calculando el número de rutas de acceso de código diferentes en el flujo del programa. Un programa que tiene un flujo de control complejo requiere más pruebas para lograr una buena cobertura de código y es menos fácil de mantener.
  3. Profundidad de herencia: indica el número de clases diferentes que heredan entre sí, hasta la clase base. La profundidad de herencia es similar al acoplamiento de clases en que un cambio en una clase base puede afectar a cualquiera de sus clases heredadas. Cuanto mayor sea este número, más profunda será la herencia y mayor será la posibilidad de modificaciones de clase base para dar lugar a un cambio importante. En Profundidad de herencia, un valor bajo es bueno y un valor alto es incorrecto.
  4. Acoplamiento de clases: mide el acoplamiento a clases únicas a través de parámetros, variables locales, tipos de valor devuelto, llamadas de método, instancias genéricas o de plantilla, clases base, implementaciones de interfaz, campos definidos en tipos externos y decoración de atributos. Según el buen diseño de software, los tipos y métodos deben tener una cohesión alta y un acoplamiento bajo. Un acoplamiento alto es indicio de un diseño difícil de reutilizar y mantener debido a sus muchas interdependencias en otros tipos.
  5. Líneas de código fuente: indica el número exacto de líneas de código fuente que están presentes en el archivo de código fuente, incluidas las líneas en blanco.
  6. Líneas de código ejecutable: Indica el número aproximado de líneas de código ejecutable o operaciones. Se trata de un recuento de número de operaciones en código ejecutable.

Versionar una API

Entender por que

  • API: Una promesa de realizar los servicios descritos cuando se le solicite de manera especifica.
  • Un contrato nunca debe ser roto unilateralmente por ninguna de las partes y las consecuencias de ello serán siempre negativas.
  • Un control de versiones de API deficiente conducirá a la inestabilidad y provocará fricciones con nuestros consumidores de API; al contrario, un control de versiones de API sólido conducirá a la estabilidad y mejorará la experiencia del desarrollador.

Saber cuando

  • Las APIS son contratos vivos y deberían poder crecer y mejorar de manera continua, sin embargo, esto no significa la ruptura del contrato continuamente. La clave está en comprender qué cambios implican la ruptura del contrato y cuáles no. Lo mas importante es mantener la estabilidad del consumo de la API.

  • Que cambios no romperan un contrato API: Los cambios continuos tienden ser aditivos: agregar nuevos campos o recursos anidados a sus representaciones de recursos, agregar nuevos puntos finales.

  • Que cambios romperán un contrato API: Los cambios importantes son cambios que requieren que el consumidor de la API realice adecuaciones para continuar consumiendo la API.

  • Eliminar o cambiar el nombre de una ruta.

  • Eliminar/Renombrar parámetros.

  • Agregue una restricción en un parámetro (isRequired)

  • Eliminar/cambiar el nombre de un elemento (campo) de solicitud o respuesta. La unica forma de minimizar las consecuencias es un plan de comunicacion sólido para atudar al consumidor de API a planificar cuándo integrar la nueva version de API.

Decidir como versionar la API Tipos de versiones de API

  1. Parámetros de Consulta (Query String) image
  2. Encabezado personalizado (Header) image
  3. Parámetros en la URI (Path) image

Ademas de decidir el tipo de versionado, también será necesario el formato del valor de la version.

  • Versionado semanticó como major.minor.patch. Por ejemplo, 1.2.0
  • Versión PRINCIPAL cuando realiza cambios que rompen el contrato de la API:
  • Versión MENOR cuando agrega funcionalidades de manera compatible con las versiones anteriores.
  • Versión PATCH cuando realiza correcciones de errores compatibles con versiones anteriores. Los valores MINOR y PATCH son transparentes para el cliente y se utilizarán internamente.