Header Ads Widget

Ticker

6/recent/ticker-posts

Los 5 mejores consejos de desarrollo para una API asesina

 

los 5 mejores consejos de desarrollo para una api asesina

El mundo avanza hacia un mundo más conectado e intrincado que nunca. El agente vinculante de aplicaciones, servicios y sistemas web, la API, se está volviendo más común y más utilizado. A medida que aumenta la ubicuidad de las API, el desarrollo de API con la experiencia del usuario final (UX) y la experiencia del desarrollador (DX) en mente es ahora más importante que nunca.

Dentro de una economía tan progresista, hay que considerar muchas estrategias de desarrollo importantes. En este artículo, ofreceremos hasta cinco consejos de desarrollo de API que, si se implementan correctamente, darán como resultado una API "asesina", convirtiendo su programa en una plataforma para un crecimiento explosivo .

1: Desarrollar con una mentalidad a largo plazo

Cuando se habla del desarrollo, la implementación y la vida útil de la API promedio, se pueden separar ampliamente los enfoques de desarrollo en dos clases: desarrollar por ahora y desarrollar para más adelante .

Desarrollar por ahora

El proceso de desarrollo más común es el enfoque "desarrollar por ahora". Estos desarrolladores están creando una API para uso inmediato , centrándose completamente en integrar conjuntos de funciones existentes y admitir conjuntos específicos de consultas. Estas API a menudo están bien documentadas, creadas con el concepto de "esto es lo que necesitamos, ahora cree lo que necesitamos". Debido a esta mentalidad, están hechos específicamente para su diseño .

La desventaja de este enfoque, sin embargo, es que solo son robustos en lo que están diseñados, y nada más. Diseñar para las necesidades y requisitos inmediatos de un servicio o sistema está muy bien, pero hace poco por el soporte a largo plazo. Piensa en el viejo adagio: dale pescado a un hombre y comerá durante un día, pero enséñale a pescar y comerá toda la vida. El diseño estricto para las necesidades actuales inhibe el crecimiento potencial, ignorando cuán robusta y diversa puede ser realmente una API .

Desarrollar para más tarde

En contraste con el enfoque anterior, el enfoque de "desarrollar para más tarde" depende del apoyo a largo plazo . Al aplicar este enfoque de desarrollo, no solo considera "¿qué necesita mi API para admitir en este momento?", Sino también " ¿qué necesita para admitir en el futuro ?". No estamos sugiriendo que una API de alojamiento de imágenes deba admitir audio, pero si tiene un concepto de API, considere varias arquitecturas (por ejemplo, REST frente a SOAP frente a Thrift ), metodologías y sistemas de seguridad, siempre teniendo en cuenta el demandas futuras de una base de usuarios posiblemente mayor y más exigente.

Si bien esto aumenta el tiempo inicial y el costo de desarrollo, los beneficios de este enfoque superan con creces los aspectos negativos. Por un lado, considerar las necesidades futuras de su base de consumidores transforma su API en un producto comercializable , aumentando su ROI potencial. Este beneficio también se traslada a la implementación: comprender y aumentar el valor y la demografía de consumo de su API es clave para una implementación exitosa .

2: ¡Sea constante y esté atento!

Los estudios de todo el mundo han demostrado que los seres humanos prosperan con la coherencia a través de patrones . El reconocimiento de patrones da sentido a un mundo que de otro modo sería caótico. El diseño de API no es diferente.

Decidir cómo su API manejará las llamadas, cómo documentará las funcionalidades de la API y las limitaciones y alcances de las diversas cuentas que se vincularán a su API son factores cruciales a considerar. Sin embargo, lo que es más importante es asegurarse de mantener la coherencia con atención . Si su API utiliza llamadas que no se ejecutan en los mismos entornos , la búsqueda de errores se convierte en una tarea ardua. Si su documentación no es coherente con la función real, corre el riesgo de confundir y segmentar su base de usuarios.

Resuelva estos problemas simplemente siendo constante. Si tiene una metodología para hacer referencia a fuentes externas, utilice esta metodología en cada referencia. Si cubre una solicitud mediante otra solicitud de varias partes, asegúrese de que no haya redundancia innecesaria. Verifique su documentación y llamadas como si fuera un usuario: ¿son claras y concisas? ¿Son consistentes? Manténgase alerta durante todo el desarrollo y compruebe constantemente estos problemas comunes.

Con documentación, brevedad y claridad es la regla de oro . De acuerdo con un artículo de MSDN titulado “Una guía del codificador para escribir documentación de API” , la documentación debe ser extensa pero concisa, con ejemplos de llamadas más complicadas y explicaciones de sistemas simplistas presentados. Un gran ejemplo de este tipo de documentación es el de la API Bit.ly. En su página de documentación para flujos de datos , el código de ejemplo, los escenarios de uso y las explicaciones en inglés simple ocupan el mismo espacio: el texto es conciso, claro y explicativo, sin ser demasiado detallado.

Hay mucho que implica diseñar API para humanos , pero para el propósito de esta sección, simplemente recuerde este axioma de Alton Brown : la organización lo liberará.

Leer más: Funcional versus útil: ¿Qué hace que una API sea útil?

3: Permitir la manipulación de datos

Los datos son tan valiosos como comprensibles. Considera lo siguiente:

EnCt2089a7215d570f2426d9633d289c37f263e282808089a7215d570f2426d9633d2qH + ZBEm7xgM

VXSxVTlUQy3wnD93BcePrTE4OddWGWxESztnRypqnJ7di9y7VfVv4Cb05IwEmS

Si recibiera estos datos, ¿qué haría con ellos? Este es un fragmento de texto cifrado, uno que se codificó con una clave de 64 bits . Una supercomputadora tardaría más de un siglo en descifrar esta pequeña cantidad de texto. En su formato actual, estos datos son inútiles; no hay forma de tomar esta cadena encriptada y utilizarla de manera significativa. Sin embargo, si lo desciframos:

Huevos, leche de almendras, harina, bicarbonato de sodio, chispas de chocolate, vainilla

Consideramos que es una lista de ingredientes muy básica para las galletas con chispas de chocolate sin gluten. Hasta que supimos cuáles eran los datos, los datos eran funcionalmente inútiles. Por lo tanto, los datos proporcionados por su API son funcionalmente inútiles a menos que se presenten en un formato utilizable.

Cuando los usuarios reciben datos de su API, considere la metodología de cómo se entregan. Delimite los datos por tipo y permita la clasificación dentro de ciertas limitaciones. En nuestro ejemplo anterior, incluso el resultado de texto sin formato decodificado podría mejorarse. Si permitimos clasificar el texto por nombre, o por si tenemos esos ingredientes o no, o incluso por precio cuando lo verificamos con las tiendas de comestibles locales, podemos crear un servicio poderoso y dinámico que permita mucha más utilidad de los datos de la API, algo común requisito entre muchos desarrolladores.

Tomemos, por ejemplo, una API de facturación y pago vinculada directamente a una cuenta corporativa. Supongamos que una solicitud GET / invoices devuelve datos que son funcionalmente inútiles y no ofrecen capacidad de clasificación. El usuario de la API tiene que examinar manualmente mucha información para encontrar lo que está buscando.

Ahora, suponga que la misma API está diseñada para permitir la manipulación de datos. En lugar de simplemente devolver todas las facturas, la API permite llamadas más específicas, como "GET / invoices? IsPaidInFull = 0". Dicha llamada devuelve una lista de facturas que aún no se han pagado en su totalidad, lo que permite al usuario evaluar rápidamente el estado de la cuenta de su cliente y el monto total de facturas pendientes. Esto lo convierte en una interfaz mucho más útil.

4: Validar e informar de forma eficaz

La sección Infernal de la epopeya del siglo XIV de Dante Alighieri, la Divina Comedia describe círculos concéntricos del infierno, junto con los pecados de quienes los ocupan y sus castigos. Si Dante hubiera escrito su epopeya en el siglo XXI y hubiera sido un desarrollador de API, habría reservado un círculo especial para los desarrolladores que no validan sus datos y devuelven mensajes de error reales, consignándolos a una eternidad de errores de "algo salió mal". .

Devolver errores inútiles que establecen lo obvio (algo salió mal), lo inútil (ERROR) o lo francamente confuso (código de error: 9442394) es una propuesta perdida: si sus usuarios no pueden averiguar qué salió mal durante los errores básicos, Dejaré de usar la API por completo. De manera similar, no devolver un JSON válido y negarse a documentar de manera efectiva lo que realmente significan los códigos de error puede hacer que un socio de desarrollo de API potencial diga la integración con sus servicios, matando aún más el crecimiento potencial de la base de usuarios.

La solución es simple: asegúrese de que todas las devoluciones de error sean comprensibles para el "usted" del pasado. Cuando comenzó a codificar, considere los errores que le dieron más dolores de cabeza. ¿Fue "error: recurso no encontrado"? Por supuesto que no, eso fue claro y conciso. Los errores que le dieron problemas fueron aquellos con formato extraño como “error10002928”, sin documentación ni referencias. Mantenga sus códigos de error simples y bien documentados, y valide los datos con códigos de error que brinden un contexto de por qué se ha rechazado un número o campo.

Los informes efectivos tienen el beneficio adicional de abrir una comunicación detallada entre los usuarios avanzados y los operadores de API a través de canales de retroalimentación, que con el tiempo disminuirán tanto el tiempo de respuesta a los errores del sistema como la frecuencia de dichos errores.

Para obtener un gran ejemplo tanto de consistencia como de validación de errores, no busque más allá de la documentación del código de error de la API de Twitter Los códigos no solo se representan de manera inteligente (es decir, si se arroja un error debido a la falta de autorización, el texto del error simplemente dice "No autorizado", emparejado con un marcador numérico), sino que están claramente establecidos y definidos en un tabla manejable y con capacidad de búsqueda.

Más consejos: 7 lecciones importantes de diseño de API

5: Soporte de tiempo de actividad y redundancia

No importa qué tan buena sea su API, podría ser el mesías de las API, pero si un usuario desarrollador no puede acceder a ella, la API es inútil por definición. Podría tener datos manipulables, soporte a prueba de futuro de tecnologías innovadoras y documentación clara y concisa, pero si no puede acceder al servicio de forma rutinaria con pocas interrupciones, está creando una cultura de fracaso y desconfianza entre sus usuarios, que esperan cerca del 100% de tiempo de actividad .

El tiempo de actividad es nuestro quinto y último consejo, ya que es una métrica maravillosa por la que podemos juzgar una API de manera integral. Representa todo lo que funciona en conjunto: si un solo elemento de una API está mal administrado, es probable que el tiempo de actividad se vea afectado. En el momento de escribir este artículo, Bit.ly informa un tiempo de actividad del 100% durante las últimas 24 horas , con una calificación de tiempo de actividad anual del 99,9% . Asimismo, la API de Twitter informa un tiempo de actividad del 100% con un tiempo de actividad promedio del 99,9% . La prueba, como dicen, está en el pudín (o en este caso, el tiempo de actividad).

La única indulgencia que se da aquí es durante el mantenimiento del servidor o el tiempo de inactividad programado temporal; se espera que esto rodee las actualizaciones y actualizaciones importantes. Pero cuando un usuario promedio solo tiene acceso a su servidor el 80% del tiempo, o solo puede llamar a un recurso el 75% del tiempo, está creando una mala experiencia de usuario que se refleja mal en la API actual, sus iteraciones futuras y el desarrollador detrás de él. El tiempo de actividad es clave y podría significar la diferencia entre la adoración y el desdén .

Conclusión

Considerar el desarrollo de su API es un esfuerzo serio. Las decisiones que tome ahora tendrán un gran impacto en su éxito futuro. Si bien estas soluciones se pueden implementar después del hecho, es mucho más fácil implementarlas al comienzo del ciclo de desarrollo . Esto no solo brindará un conjunto de funciones más completamente integrado, sino que también le brindará un producto con una documentación final y una experiencia de usuario más simples.

Estos cinco conceptos de diseño pueden ser simples, pero las implicaciones de sus aplicaciones son engañosamente enormes: implementarlos puede conducir a un crecimiento explosivo, una alta adopción por parte de los usuarios y estadísticas de uso a largo plazo.

Publicar un comentario

0 Comentarios