Header Ads Widget

Ticker

6/recent/ticker-posts

Prácticas recomendadas para la creación de SDK para API


Si bien es extremadamente importante tener una experiencia de desarrollador de API de calidad, no se detiene en un excelente diseño de API o en el nivel de documentación. Uno de los elementos más importantes de una gran experiencia de desarrollador es el SDK .

Para los desarrolladores de aplicaciones, un SDK suele ser el punto de entrada a los elementos dentro de la API. Cada API bifurcada, cada función secundaria y cada funcionalidad de empresa a empresa podrían ser impulsadas principalmente por el SDK y sus funciones. Tener una mala experiencia de desarrollador para los SDK es similar a envenenar el sistema de raíces de un árbol frutal; incluso si creciera, la fruta que produce estaría envenenada o, al este, muy amarga.

Hoy, vamos a discutir cómo hacer que el ecosistema SDK sea lo más fuerte posible, de hecho, hacer que nuestras raíces sean saludables, robustas y poderosas. Ofreceremos algunas prácticas recomendadas para crear un buen SDK y, por lo tanto, formar una red de API sólida y sólida.

¿Qué es un SDK?

Antes de poder dar un buen consejo sobre la creación de un SDK, deberíamos definir qué es un SDK . En pocas palabras, un SDK es un kit de desarrollo de software que incluye toda la información y las piezas necesarias para crear una aplicación específica. En este caso, un SDK para una API incluye toda la información y las piezas necesarias para crear una aplicación que utilice esa API de formas nuevas y poderosas; en otras palabras, actúa como un sistema de guía para la integración.

Idealmente, un SDK debería incluir bibliotecas, herramientas, documentación relevante muestras de código e implementaciones, explicaciones y ejemplos de procesos, guías para el uso del desarrollador, definiciones de limitaciones y cualquier otra oferta adicional que facilite la creación de funciones que aprovechan la API.

Para obtener más información, lea: ¿Cuál es la diferencia entre una API y un SDK?

Mejores prácticas

Teniendo esto en cuenta, ¿qué mejores prácticas podemos identificar para la creación de SDK?

Mantenlo simple

Cualquier SDK, y realmente, cualquier API, solo vale la pena si el usuario promedio puede utilizarlo. Las bases de código demasiado complejas, las implementaciones arcaicas y las metodologías laberínticas pueden obstaculizar el uso, matando un SDK y sus proyectos asociados con una eficiencia asombrosa. Garantizar la simplicidad en todas las etapas es una gran base sobre la que construir.

Si bien existe una amplia gama de enfoques para este problema, existen pasos prácticos que los desarrolladores pueden tomar de manera proactiva para simplificar el resultado. En primer lugar, priorice las clases y métodos que se utilizan con más frecuencia. Esto permitirá que el SDK muestre las funciones utilizadas por el usuario sin ofuscar las opciones con una avalancha de métodos o funciones que en realidad no se pueden utilizar.

Como parte de esto, el código base en sí puede ayudar a garantizar la simplicidad en el SDK. Utilice la menor cantidad de parámetros posible, usando solo lo que sea necesario para realizar la función específica. Como corolario de esto, no simplifique demasiado y combine múltiples funciones en un solo conjunto de parámetros a menos que estén relacionados; aunque esto puede parecer lo último en simplificación, una vez que va demasiado lejos, en realidad comienza a agregar más complejidad de la que vale. .

La simplicidad se trata de forma y función; tenga esto en cuenta mientras simplifica la base de código del SDK.

Hágalo utilizable

Como se mencionó anteriormente, un SDK se valora por su función . Como tal, garantizar la usabilidad es fundamental. Esto se puede hacer de distintas maneras. En primer lugar, proporciona una guía de uso, tal vez en forma de un Getting Started imprimación, puede ayudar a introducir al usuario no sólo el SDK en sí, pero las complejidades y las peculiaridades de su enfoque de código.

Idealmente, un usuario debería poder comenzar a usar el SDK dentro de los 5 a 10 minutos posteriores a la introducción, asumiendo que está familiarizado con el lenguaje y la función del código base que representa. Estructura tu guía de introducción en torno a este objetivo.

También es muy importante asegurarse de que la mayor cantidad posible de usuarios pueda utilizar su servicio. En consecuencia, ofrecer SDK que se integran en la base de código de la API en una amplia variedad de idiomas puede ayudar a expandir la gama de opciones disponibles para más usuarios.

Sin embargo, es importante tener en cuenta que a medida que amplía sus ofertas de idiomas, debe asegurarse de que está respaldando correctamente estas ofertas de integración. Es importante utilizar tipos de archivos, sistemas de codificación y métodos de código generales correctos, ya que utilizar un lenguaje común con una sintaxis propietaria no es mejor que utilizar un lenguaje no común en primer lugar.

Relacionado: ¿Qué idiomas deberían admitir sus bibliotecas auxiliares de API?

Asignar puntos finales correctamente

Los SDK son como hojas de ruta: proporcionan una guía para la navegación. Por lo tanto, al crear SDK, asegúrese de que su asignación sea correcta.

En realidad, los puntos finales deben mapearse de la misma manera en su SDK que en su API. Aclare estas conexiones en cuanto a lo que se relaciona con qué, por qué es así y cuáles son las funciones previstas y las respuestas esperadas.

Asegúrese de que los SDK se actualicen continuamente El código obsoleto, los nombres de clases, las funciones, etc.no residen en el SDK si ya no residen en la API; dejarlos adentro sería similar a tener carreteras cruzadas e intersecciones en un mapa que en realidad no existen, anulando mucho del valor de navegación para el usuario medio.

Como complemento de esto, asegúrese de que las funciones se correspondan con su función y estén debidamente nombradas . Si bien esta es una buena forma para la API en sí, en el SDK, podría decirse que es aún más importante. usernameSubmites más apropiado que unmeSbt, independientemente de si el segundo nombre podría ser una abreviatura personal utilizada por el desarrollador por velocidad o por puro hábito. El uso de nombres claros y consistentes no solo facilitará la utilización del SDK, sino que también dará como resultado una comunicación más clara de la función esperada, actuando como una especie de documentación ad hoc.

Finalmente, asegúrese de que cualquier nueva funcionalidad se agregue y defina inmediatamente dentro del SDK, y que esté anotada en cualquier documentación . Las clases ocultas solo deberían existir por razones de seguridad, no porque alguien olvidó agregarlas. Esto, y sinceramente todas las sugerencias anteriores, se implementan fácilmente cuando se utiliza cualquiera de las muchas opciones que ofrecen la generación automática de SDK y la generación de documentación desde una base de código API.

Lea también: Cómo implementar la sincronicidad de API a SDK

Documente también el SDK

Es común pensar en un SDK como una forma de documentación para la API además de una herramienta de desarrollo. Sin embargo, centrarse solo en el SDK como una forma de documentación da como resultado una situación en la que las personas con mentalidad técnica, que es más probable que comprendan las funciones en primer lugar, son las únicas con documentación valiosa en la que apoyarse.

En consecuencia, proporcionar una amplia documentación no solo de la API, sino también del SDK, es increíblemente importante. Aparte del ensayo y error, este será el sistema principal que los desarrolladores, tanto experimentados como no, utilizarán como punto de integración. Una documentación deficiente tanto del SDK como de sus funciones interrumpiría este flujo de trabajo. Asegúrese de escribir con claridad tanto para los usuarios técnicos como para los usuarios habituales para garantizar una comprensión universal, sin que la jerga se confunda.

Una gran herramienta en este espacio es el uso de archivos Léame y registros de cambios . Estos ayudarán a explicar directamente la versión actual del SDK, así como la mentalidad del equipo de desarrollo cuando los cambios están justificados. Esto también ayudará a garantizar una línea de comunicación entre desarrolladores y usuarios, que es fundamental para una interacción y una experiencia de usuario saludables en general.

Sobre los métodos de comunicación, lea: Métodos para comunicar el cambio de API de manera efectiva

Publicar apropiadamente

También es muy importante asegurarse de que se pueda acceder a su API de manera adecuada y que este acceso sea navegable públicamente. Si su base de usuarios se preocupa principalmente por la bifurcación, la seguridad y el desarrollo de código abierto, tener su SDK publicado utilizando GitHub y sus repositorios asociados como un proyecto de código abierto puede garantizar resultados excelentes.

Alternativamente, si su API está cerrada o requiere privacidad de la base de código, entonces tiene más sentido utilizar un SDK patentado y una metodología de documentación, con el entendimiento de que esto viene con ciertas advertencias y se deben medir las expectativas.

Los desarrolladores también deberían considerar la posibilidad de publicar sin conexión a Internet, lo que permite la documentación y la lectura del SDK sin conexión a Internet. Esto se puede hacer de varias formas, tan complejas como una aplicación de escritorio especialmente diseñada hasta el archivo PDF más simple. Independientemente del método, esto debe considerarse dependiente de su base de usuarios y sus necesidades específicas, y las estipulaciones de las políticas de su plataforma .

Pensamientos finales

En esencia, un SDK es un conducto directo a la mente del creador de la API . Los diversos métodos, sistemas, integraciones y ofertas del creador de API no solo están presentes (como lo están en la propia API), sino que están bien explicados y demostrados; de esta manera, un SDK ofrece un conjunto de herramientas para la creación, sí, pero también ofrece un canal de comunicación que es directo, personalizable y totalmente administrado por el proveedor de API para explicar y describir de una manera específica.

Tanto una herramienta para la creación como para la comunicación, un SDK debe considerarse un sistema de doble faceta de extrema importancia.

La creación de un SDK deficiente también garantiza que cualquier comunicación entre el desarrollador y el usuario sea igualmente deficiente, llena de conjeturas y extrapolaciones que pueden o no ser ciertas. Con este fin, seguir las pocas prácticas descritas en este documento garantizará que su SDK, así como los sistemas que lo utilizan, sean tan buenos como sea posible.

¿Tiene ideas adicionales sobre las mejores prácticas para crear SDK ? ¡Comenta abajo!

 

Publicar un comentario

0 Comentarios