Skip to main content

Definicion de la API

A la hora de definir una API es importante no olvidar que el desarrollador va a ser el cliente al que nuestro proyecto va dirigido y que el éxito de nuestra API depende del uso que los desarrolladores hagan de ella, por lo que debemos facilitarles la vida en todo momento y en todos los aspectos posibles. Toda API debe ser Developer-friendly.

Haz que tu API sea lo más sencilla e inteligible posible. Huye de todo aquello que pueda suponer ambigüedad, confusión o un mayor esfuerzo o complejidad de uso para el desarrollador.

Introduccion

Con la apuesta de los clientes por abrir lógica de aplicaciones a terceros, externos o propios, se ha visto necesaria la definición, creación, y uso de numerosas APIs por diferentes equipos y departamentos. Por este motivo, y con el fin de ayudar y homogeneizar su construcción, el equipo de CloudAppi ha creado este documento en el que se refleja los criterios a seguir a la hora de diseñar una API.

Este documento se basa en las guías de buenas prácticas publicadas en OData . No hemos querido crear un documento que sea una unión de lo anterior, sino que le hemos aplicado nuestra experiencia en la definición y gestión de APIs.

Consideraciones Generales​

El mundo de las APIs es muy amplio, tanto que en los últimos años no ha parado de cambiar, renovarse y crecer. Lo que hace unos años se había convertido en un estándar, ahora es tecnología obsoleta.

Existen multitud de arquitecturas a la hora de crear una API: XML-RPC, SOAP, REST, pero las APIs que se definan bajo la asesoría de CloudAppi, deben seguir, en la medida de lo posible, todos los principios REST.

A la hora de definir una API, se debería tener en cuenta las siguientes consideraciones generales:

  • Protocolo a utilizar: En este caso, según REST, siempre utilizaremos el protocolo HTTPS.
  • Seguridad de la API: La mayor parte de la seguridad de la API se delega en el maestro de usuarios utilizado por el cliente. Parte de la seguridad estará delegada en el API Gateway de AWS, pero no debemos de entender que es cosa de todos y que hay aspectos que tanto la implementación de la API, como los backend como los usuarios que las consumen deben de tener en cuenta.
  • Formato de entrada y salida de datos: Se aconseja que se soporte JSON como formato de entrada y salida de datos.
  • Estándar para la definición de la API: RESTFul no es suficiente para poder definir bien y de forma uniforme dentro de la empresa, por lo que se creará un estándar de definición de APIs de RIMAC que cumpla con las necesidades de la empresa.

Principios REST​

En la actualidad se usa genéricamente el término REST (Representational State Transfer) para describir cualquier interfaz que utiliza JSON y HTTPS sin las abstracciones adicionales de otros protocolos anteriores como SOAP.

REST afirma que la web es escalable como resultado de una serie de diseños fundamentales que deben seguir todos aquellos servicios que deseen seguir esta arquitectura:

  • Un protocolo cliente/servidor sin estado: cada mensaje HTTP contiene toda la información necesaria para comprender la petición. Como resultado, ni el cliente ni el servidor necesitan recordar ningún estado de las comunicaciones entre mensajes. Sin embargo, en la práctica muchas aplicaciones basadas en HTTP utilizan cookies y otros mecanismos para mantener el estado de la sesión (algunas de estas prácticas, como la reescritura de URLs, no son permitidas por REST)

  • Un conjunto de operaciones bien definidas que se aplican a todos los recursos de información: HTTP en sí define un conjunto pequeño de operaciones, las más importantes son POST, GET, PUT, PATCH** y DELETE. Con frecuencia estas operaciones se equiparan a las operaciones CRUD que se requieren para la persistencia de datos, aunque POST no encaja exactamente en este esquema.

  • Una sintaxis universal para identificar los recursos: En una arquitectura REST, cada recurso es direccionable únicamente a través de su

  • El uso de hipermedios, tanto para la información de la aplicación como para las transiciones de estado de la aplicación: la representación de este estado en un sistema REST son típicamente HTML, XML o JSON. Como resultado de esto, es posible navegar de un recurso REST a muchos otros, simplemente siguiendo enlaces sin requerir el uso de registros u otra infraestructura adicional.

Implementando los principios RESTful​

Los principios REST definen los elementos a tener en cuenta para que nuestra API sea RESTFul, Define, entre otras cosas, cuáles son los métodos HTTP que se deben utilizar y cómo deben estructurarse las URIs para que sean user-friendly. Posee los siguientes principios básicos:

  • Una URL identifica un recurso.

Por ejemplo:
GET http://api.rimac.com/api-gestor-documental/v1/expedientes

  • Uniformidad de interfaz. Los recursos se manipulan a través de los métodos HTTP (PUT, GET, POST, PATCH y DELETE).

    • POST crea el recurso
    • PUT permite sustituir un recurso
    • PATCH permite modificar un recurso parcialmente.
    • DELETE lo elimina
    • GET permite consultarlo.

  • Uniformidad de salida. Deben usarse los códigos de respuesta HTTP:

    • 1xx: Informacional

    • 2xx: Resultado satisfactorio.

      • 200: OK
      • 201: Recurso creado
      • 202: Aceptado, pero la petición se está procesando (para peticiones asíncronas).
      • 204: No content
      • 206 Contenido parcial. Se usa en casos en los que se devuelve contenido paginado.

    • 3xx: Redirecciones

    • 4xx: Errores de cliente.

      • 400: Parámetros incorrectos
      • 401: No autorizado
      • 403: Recurso prohibido
      • 404: Recurso no encontrado
      • 409: Conflicto
      • 413: Solicitud demasiado grande
      • 415: Tipo de medio no admitido
      • 429: peticiones excesivas

    • 5xx: Errores de servidor

      • 500: Error interno del servidor
      • 503: Servicio no disponible
      • 504: Gateway timeout / Error de integración

  • Mensajes autodescriptivos: Los recursos están desacoplados de la representación.

  • Los mensajes se pueden devolver en varios formatos. Dependiendo del Accept, el API es capaz de retornar una variedad de formatos, en principio se devuelve JSON, salvo las excepciones expuestas anteriormente debidas a la entrada/salida de archivos de gran tamaño.

  • Todas las peticiones son sin estado.

Seguridad de la API​

La gestión de usuarios se realiza por Cognito y existen dos tipos de seguridad implementada en RIMAC:

AWS Signature Version 4 (HMAC Signature)

Signature Version 4 es el proceso para añadir información de autenticación a las solicitudes de AWS enviadas por HTTP. Por seguridad, la mayoría de las solicitudes de AWS se firman con una clave de acceso, que se compone de un ID de clave de acceso y una clave de acceso secreta.

La autenticación con AWS Signature Version 4 proporciona algunos o todos los siguientes elementos, según cómo elija firmar su solicitud

  • Verificación de la identidad del solicitante
  • Protección de datos en tránsito
  • **Proteger contra la reutilización de las partes firmadas de la solicitud**

Puede expresar la información de autenticación mediante uno de los siguientes métodos:

  • Header Authorization
  • Query Parameter

JSON Web Token (JWT)

JWT es un estándar abierto que define una forma compacta y autónoma de transmitir información de forma segura. Esta información se puede verificar y confiar porque está firmada digitalmente. Los JWT se pueden firmar usando una clave secreta con el algoritmo HMAC o un par de claves (pública y privada) usando RSA o ECDSA .

Formatos de entrada salida​

A la hora de definir una API hay que definir cuáles van a ser los formatos de entrada y salida de datos. Por regla general se deberá aceptar JSON, aunque también se pueden obtener imágenes u otros tipos de datos. Es posible devolver formatos codificados embebidos en la respuesta JSON, siempre y cuando no excedan de 5 MB.

El tipo de formato de entrada / salida se deberá especificar en las cabeceras de las peticiones con los estándares que ya existen en HTTP:

  • Accept: Permite especificar el formato de datos de entrada que acepta el cliente:

    • Accept: application/json

  • Content-type: Permite especificar el formato de datos de salida de la petición y/o de la respuesta:

    • Content-Type: application/json

  • Accept-Language: permite indicar el lenguaje de la respuesta. Por defecto se devuelve en Español.

    • Accept-Language: EN