10 principios para el desarrollo web y diseño de API web

Fecha de la noticia: 20-01-2025

Foto de un ordenador

El diseño de API web es una disciplina fundamental para el desarrollo de aplicaciones y servicios, al facilitar el intercambio fluido de datos entre diferentes sistemas. En el contexto de las plataformas de datos abiertos, las API cobran especial importancia, ya que permiten a los usuarios acceder de manera automática y eficiente a la información necesaria, ahorrando costes y recursos.

Este artículo explora los principios esenciales que deben guiar la creación de API web eficaces, seguras y sostenibles, en base a los principios recopilados por el Grupo de Arquitectura Técnica ligado a World Wide Web Consortium (W3C), siguiendo estándares éticos y técnicos. Aunque estos principios hacen referencia al diseño de API, muchos son aplicables al desarrollo web en general.

Se busca que los desarrolladores puedan garantizar que sus API no solo cumplan con los requisitos técnicos, sino que también respeten la privacidad y seguridad de los usuarios, promoviendo una web más segura y eficiente para todos.

En este post, analizaremos algunos consejos para los desarrolladores de las API y cómo se pueden poner en práctica.

Prioriza las necesidades del usuario

Al diseñar una API, es crucial seguir la jerarquía de necesidades establecida por el W3C:

  • Primero, las necesidades del usuario final.
  • Segundo, las necesidades de los desarrolladores web.
  • Tercero, las necesidades de los implementadores de navegadores.
  • Por último, la pureza teórica.

Así podremos impulsar una experiencia de usuario que sea intuitiva, funcional y atractiva. Esta jerarquía debe guiar las decisiones de diseño, aunque reconociendo que en ocasiones estos niveles se interrelacionan: por ejemplo, una API más fácil de usar para los desarrolladores suele resultar en mejor experiencia para el usuario final.

Garantiza la seguridad

Garantizar la seguridad al desarrollar una API es crucial para proteger, tanto los datos de los usuarios, como la integridad del sistema. Una API insegura puede ser un punto de entrada para atacantes que buscan acceder a información sensible o comprometer la funcionalidad del sistema. Por ello, al añadir nuevas funcionalidades, debemos cumplir las expectativas del usuario y garantizar su seguridad.

En este sentido, es esencial considerar factores relacionados con la autenticación de usuarios, encriptación de datos, validación de entradas, gestión de tasas de solicitud (o Rate Limiting, para limitar la cantidad de solicitudes que un usuario puede hacer en un periodo determinado y evitar ataques de denegación de servicio), etc. También es necesario monitorear continuamente las actividades de la API y mantener registros detallados para detectar y responder rápidamente a cualquier actividad sospechosa.

Desarrolla una interfaz de usuario que transmita confianza

Es necesario considerar cómo las nuevas funcionalidades impactan en las interfaces de usuario. Las interfaces deben ser diseñadas para que los usuarios puedan confiar y verificar que la información proporcionada es genuina y no ha sido falsificada. Aspectos como la barra de direcciones, los indicadores de seguridad y las solicitudes de permisos deben dejar claro con quién se están interactuando y cómo.

Por ejemplo, la función alert de JavaScript, que permite mostrar un cuadro de diálogo modal que parece parte del navegador, es un caso histórico que ilustra esta necesidad. Esta función, creada en los primeros días de la web, ha sido frecuentemente utilizada para engañar a usuarios haciéndoles creer que están interactuando con el navegador, cuando en realidad lo hacen con la página web. Si esta funcionalidad se propusiera hoy, probablemente no sería aceptada por estos riesgos de seguridad.

Pide consentimiento explicito a los usuarios

En el contexto de satisfacer una necesidad de usuario, una página web puede utilizar una función que suponga una amenaza. Por ejemplo, el acceso a la geolocalización del usuario puede ser de ayuda en algunos contextos (como una aplicación de mapas), pero también afecta a la privacidad.

En estos casos es necesario que el usuario consienta su uso. Para ello:

  • El usuario debe entender a qué está accediendo. Si no puedes explicar a un usuario tipo a qué está consintiendo de forma inteligible, deberás reconsiderar el diseño de la función.
  • El usuario debe poder elegir entre otorgar o rechazar ese permiso de manera efectiva. Si se rechaza una solicitud de permiso, la página web no podrá hacer nada que el usuario crea que ha descartado.

Al pedir consentimiento, podemos informar al usuario de qué capacidades tiene o no tiene la página web, reforzando su confianza en la seguridad del sitio. Sin embargo, el beneficio de una nueva función debe justificar la carga adicional que supone para el usuario decidir si otorga o no permiso para una función.

Usa mecanismos de identificación adecuados al contexto

Es necesario ser transparente y permitir a las personas controlar sus identificadores y la información adjunta a ellos que proporcionan en diferentes contextos en la web.

Las funcionalidades que utilizan o dependen de identificadores vinculados a datos sobre una persona conllevan riesgos de privacidad que pueden ir más allá de una sola API o sistema. Esto incluye datos generados pasivamente (como su comportamiento en la web) y aquellos recopilados activamente (por ejemplo, a través de un formulario). En este sentido, es necesario entender el contexto en el que se usarán y cómo se integrarán con otras funcionalidades de la web, asegurando de que el usuario pueda dar un consentimiento adecuado.

Es recomendable diseñar API que recopilen la mínima cantidad de datos necesarios y usar identificadores temporales de corta duración, a menos que sea absolutamente necesario un identificador persistente.

Crea funcionalidades compatibles con toda la gama de dispositivos y plataformas

En la medida de lo posible, asegura que las funcionalidades de la web estén operativas en diferentes dispositivos de entrada y salida, tamaños de pantalla, modos de interacción, plataformas y medios, favoreciendo la flexibilidad del usuario.

Por ejemplo, los modelos de diseño 'display: block', 'display: flex' y 'display: grid' en CSS, por defecto, colocan el contenido dentro del espacio disponible y sin solapamientos. De este modo funcionan en diferentes tamaños de pantalla y permiten a los usuarios elegir su propia fuente y tamaño sin causar desbordamiento de texto.

Agrega nuevas capacidades con cuidado

Añadir nuevas capacidades a la web requiere tener en consideración las funcionalidades y el contenido ya existentes, para valorar cómo va a ser su integración. No hay que asumir que un cambio es posible o imposible sin verificarlo primero.

Existen muchos puntos de extensión que permiten agregar funcionalidades, pero hay cambios que no se pueden realizar simplemente añadiendo o eliminando elementos, porque podrían generar errores o afectar a la experiencia de usuario. Por ello es necesario verificar antes la situación actual, como veremos en el siguiente apartado.

Antes de eliminar o cambiar funcionalidades, comprende su uso actual

Es posible eliminar o cambiar funciones y capacidades, pero primero hay que conocer bien la naturaleza y el alcance de su impacto en el contenido existente. Para ello puede ser necesario investigar cómo se utilizan las funciones actuales.

La obligación de comprender el uso existente se aplica a cualquier función de la que dependan los contenidos. Las funciones web no se definen únicamente en las especificaciones, sino también en la forma en que los usuarios las utilizan.

La práctica recomendada es priorizar la compatibilidad de las nuevas funciones con el contenido existente y el comportamiento del usuario. En ocasiones, una cantidad significativa de contenido puede depender de un comportamiento concreto. En estas situaciones, se desaconseja eliminar o cambiar dicho comportamiento.

Deja la web mejor de lo que la encontraste

La forma de añadir nuevas capacidades a una plataforma web es mejorando la plataforma en su conjunto, por ejemplo, sus características de seguridad, privacidad o accesibilidad.

La existencia de un defecto en una parte concreta de la plataforma no debe servir de excusa para añadir o ampliar funcionalidades adicionales con el fin de solucionarlo, ya que con ello se pueden duplicar problemas y disminuir la calidad general de la plataforma. Siempre que sea posible, hay que crear nuevas capacidades web que mejoren la calidad general de la plataforma, mitigando los defectos existentes de forma global.

Minimiza los datos del usuario

Hay que diseñar las funcionalidades para que sean operativas con la mínima cantidad necesaria de datos aportados por el usuario para llevar a cabo sus objetivos . Con ello, limitamos los riesgos de que se divulguen o utilicen indebidamente.

Se recomienda diseñar las API de forma que a los sitios web les resulte más fácil solicitar, recopilar y/o transmitir una pequeña cantidad de datos (datos más granulares o específicos), que trabajar con datos más genéricos o masivos. Las API deben proporcionar granularidad y controles de usuario, en particular si trabajan sobre datos personales.

Otras recomendaciones

El documento también ofrece consejos para el diseño de API utilizando diversos lenguajes de programación. En este sentido, proporciona recomendaciones ligadas a HTML, CSS, JavaScript, etc. Puedes leer las recomendaciones aquí.

Además, si estás pensando en integrar una API en tu plataforma de datos abiertos, te recomendamos la lectura de la Guía práctica para la publicación de Datos Abiertos usando APIs.

Siguiendo estas indicaciones podrás desarrollar sitios web consistentes y útiles para los usuarios, que les permitan alcanzar sus objetivos de manera ágil y optimizando recursos.