\u00bfQu\u00e9 es la documentaci\u00f3n API?<\/h2>\r\n
La documentaci\u00f3n de la API es un conjunto de instrucciones que le dice a los desarrolladores y a otras partes interesadas c\u00f3mo utilizar su API y sus servicios para un fin espec\u00edfico. Normalmente contiene ejemplos de c\u00f3digo, tutoriales y detalles sobre las funciones, clases y tipos de retorno. B\u00e1sicamente proporciona a los desarrolladores toda la informaci\u00f3n que necesitan para construir integraciones con la API y hacer llamadas API con el software.<\/p>\r\n
![\"api](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/10\/api_documentation_using_document360.png\")
<\/p>\r\n
Las llamadas API son un tipo de petici\u00f3n que hace el desarrollador de terceros a la API de la plataforma. Las llamadas API se describen en la documentaci\u00f3n y le dicen al desarrollador exactamente qu\u00e9 pueden pedir a la API que haga y c\u00f3mo.<\/p>\r\n
La documentaci\u00f3n de la API explica claramente sus extremos, interpreta por qu\u00e9 quieres usarlos y da ejemplos muy espec\u00edficos de c\u00f3mo quieres usarlos.<\/p>\r\n
Las APIs son importantes porque significa que los desarrolladores no tienen que seguir construyendo las mismas soluciones de software una y otra vez desde cero. APIs significa que los desarrolladores pueden aprovechar otras plataformas que ya han sido creadas e integrar su funcionalidad en sus propios programas. Muchas grandes plataformas tienen APIs, incluyendo Twitter y GitHub.<\/p>\r\n<\/div>\r\n
Tipos de API<\/h2>\r\n<\/div>\r\n\r\nPara el equipo<\/h3>\r\n
Usted puede tener una API que sea interna a su empresa y por lo tanto destinada a ser utilizada \u00fanicamente por miembros de su equipo. El prop\u00f3sito de este tipo de API ser\u00eda agilizar la transferencia de datos entre equipos y sistemas, para que los desarrolladores internos de su empresa sean los encargados de usar esta API.<\/p>\r\n<\/div>\r\n
\r\nPara los socios<\/h3>\r\n
Las APIs asociadas se comparten fuera de la organizaci\u00f3n, pero s\u00f3lo con aquellos que tienen una relaci\u00f3n de negocios con la empresa que proporciona la API. S\u00f3lo los clientes autorizados tienen acceso a la API y, como consecuencia, las medidas de seguridad tienden a ser m\u00e1s estrictas con este tipo de API.<\/p>\r\n<\/div>\r\n
\r\nPara los usuarios finales<\/h3>\r\n
APIs para usuarios finales o APIs abiertas<\/a> pueden ser utilizadas por cualquier desarrollador sin restricciones. Este tipo de APIs no tienen medidas de autenticaci\u00f3n y autorizaci\u00f3n especialmente estrictas porque los proveedores quieren que la API sea adoptada por tantos desarrolladores como sea posible. A veces este tipo de API estar\u00e1 disponible por una cuota de suscripci\u00f3n que es escalada dependiendo del n\u00famero de llamadas de la API que se est\u00e9n realizando.<\/p>\r\n<\/div>\r\n\r\n\u00bfQui\u00e9n escribe la documentaci\u00f3n API?<\/h2>\r\n
Naturalmente, como desarrolladores son los que construyen las APIs a menudo tienen la tarea de escribir la documentaci\u00f3n. Desafortunadamente, la documentaci\u00f3n impulsada por el desarrollador a menudo puede ser demasiado t\u00e9cnica porque los desarrolladores est\u00e1n tan cerca del tema. La documentaci\u00f3n escrita por los desarrolladores tambi\u00e9n puede caer en el camino, ya que los desarrolladores est\u00e1n realmente enfocados en construir y mantener la API.<\/p>\r\n
Por esta raz\u00f3n, muchas empresas emplean a escritores t\u00e9cnicos profesionales para crear su documentaci\u00f3n API. Los escritores t\u00e9cnicos tienen la capacidad t\u00e9cnica de entender la API y las habilidades creativas para poder escribir contenido atractivo para los usuarios finales que son desarrolladores.<\/p>\r\n
Los desarrolladores de la API proporcionan al escritor t\u00e9cnico la informaci\u00f3n que necesitan para poder documentar la API con exactitud. Si faltan partes en la documentaci\u00f3n, los desarrolladores pueden ayudar al escritor t\u00e9cnico a rellenarlas, con el resultado final de tener un documento claro y accesible para su p\u00fablico objetivo.<\/p>\r\n
Tambi\u00e9n, revisa nuestro art\u00edculo en C\u00f3mo crear una experiencia encantadora de desarrollador API con la documentaci\u00f3n<\/a><\/em><\/p>\r\n<\/div>\r\n\r\nBeneficios de la documentaci\u00f3n de API<\/h2>\r\n
Para los proveedores que quieren ofrecer una API, desarrollar documentaci\u00f3n puede tener muchos beneficios importantes para su organizaci\u00f3n.<\/p>\r\n
Mejora la experiencia del desarrollador de API<\/h3>\r\n
En primer lugar, la documentaci\u00f3n de API mejora la experiencia del desarrollador. No importa lo bueno que sea tu API si los desarrolladores potenciales no entienden c\u00f3mo usarla. Una buena documentaci\u00f3n de API ayuda a los desarrolladores a entender los diferentes puntos finales que tiene para ofrecer y ejemplos de casos de uso particulares. Cuando mejoras la experiencia del desarrollador incrementas el n\u00famero de usuarios potenciales que puedes atraer a tu producto.<\/p>\r\n
Reduce el tiempo de uso interno de desarrolladores internos o socios externos
\r\nUna buena documentaci\u00f3n API significa que tus equipos de apoyo y \u00e9xito necesitan pasar menos tiempo incorporando nuevos desarrolladores internos o socios externos. Los nuevos usuarios de su API tienen toda la informaci\u00f3n que necesitan para empezar con su plataforma y configurarse para el \u00e9xito. Cuando los procesos est\u00e1n documentados, elimina la necesidad de que determinados miembros del equipo intervengan.<\/p>\r\n
Mantenimiento de producto eficiente y actualizaciones m\u00e1s r\u00e1pidas<\/h3>\r\n
Cuando documentas tu API de forma efectiva, significa que puedes administrar el mantenimiento de tu producto y actualizarlo m\u00e1s r\u00e1pidamente. Con la documentaci\u00f3n API usted sabe exactamente qu\u00e9 debe hacer su producto y c\u00f3mo debe ayudar a los usuarios finales. La documentaci\u00f3n le da una visi\u00f3n m\u00e1s \u00edntima de la API y le permite desplegar actualizaciones m\u00e1s r\u00e1pidas que ser\u00e1n adoptadas por los usuarios.<\/p>\r\n
Ayuda tanto a los usuarios internos como externos en la integraci\u00f3n de la API y sus capacidades<\/h3>\r\n
Uno de los principales beneficios de documentaci\u00f3n de la API<\/a> es que ayuda a los usuarios internos y externos a entender la API, para qu\u00e9 se puede usar, y c\u00f3mo se puede desplegar la API para sus propios fines. Si no explica las capacidades potenciales de la API, entonces los nuevos usuarios no sabr\u00e1n c\u00f3mo usarla y experimentar\u00e1n una lenta adopci\u00f3n de productos. Los usuarios Potential de una API usan la documentaci\u00f3n como una manera de tomar la decisi\u00f3n de usar o no su producto.<\/p>\r\nEl Ir a la Fuente de los Miembros del Equipo para referirse a los Objetivos de la API<\/h3>\r\n
Los miembros del equipo interno de su organizaci\u00f3n pueden referirse a la documentaci\u00f3n de la API cuando quieren familiarizarse con los objetivos de su API. Incluso aquellos que no participaron directamente en la construcci\u00f3n de la API o en la escritura de la documentaci\u00f3n comprender\u00e1n el prop\u00f3sito de la API y podr\u00e1n apoyar el trabajo del equipo de desarrollo de la API.<\/p>\r\n
Permite identificar errores r\u00e1pidamente y problemas<\/h3>\r\n
Cuando documentas la API, esto te permite identificar r\u00e1pidamente errores y problemas como resultado de la prueba de la API para documentar todas sus caracter\u00edsticas. Si tu API no funciona como est\u00e1 dise\u00f1ado, esta retroalimentaci\u00f3n puede ser transmitida al equipo de desarrollo de la API, quien puede tomar medidas para solucionar cualquier problema. El resultado es una API m\u00e1s profesional y eficaz que funciona como se esperaba.<\/p>\r\n<\/div>\r\n
\r\n\r\nUn software intuitivo de base de conocimiento para agregar f\u00e1cilmente su contenido e integrarlo en cualquier aplicaci\u00f3n. \u00a1Pru\u00e9balo!<\/p>\r\nComenzar<\/a><\/div>\r\n![\"Document360\"](\"https:\/\/document360.com\/wp-content\/themes\/document360\/images\/blog-call-to-action.png\")
<\/div>\r\n<\/div>\r\n\r\nLa estructura de la documentaci\u00f3n de API – Dise\u00f1o y funci\u00f3n<\/h2>\r\nUna l\u00ednea externa<\/h3>\r\n
El contorno de la documentaci\u00f3n de su API tambi\u00e9n es conocido como la descripci\u00f3n. Contiene un resumen de la API y su prop\u00f3sito, y puede informar a los usuarios potenciales sobre los beneficios de usar esta API sobre otros.<\/p>\r\n
Tutoriales<\/h3>\r\n
Los tutoriales forman la parte principal de la API y su prop\u00f3sito es ense\u00f1ar a los usuarios el concepto de la API y c\u00f3mo utilizarla eficazmente. Normalmente contiene gu\u00edas paso a paso para c\u00f3mo integrar la API y c\u00f3mo se ve el funcionamiento apropiado.<\/p>\r\n
Autenticaci\u00f3n<\/h3>\r\n
La autenticaci\u00f3n es la forma en que el proveedor mantiene los datos de la API a salvo para los desarrolladores y usuarios finales, por lo que podr\u00eda tener m\u00faltiples esquemas de autenticaci\u00f3n. La documentaci\u00f3n de la API explica cada m\u00e9todo de autenticaci\u00f3n para que los usuarios entiendan c\u00f3mo acceder a la API.<\/p>\r\n
Definici\u00f3n de punto final<\/h3>\r\n
Las definiciones de los endpoints de la API son el punto en el que la API se conecta con el programa de software. El punto en el que la API interact\u00faa con otro sistema se considera el punto final, y puede incluir una URL del servidor o servicio.<\/p>\r\n
Estado y c\u00f3digos de error<\/h3>\r\n
Las APIs utilizan los c\u00f3digos de estado y de error para informar a los desarrolladores cuando la API no est\u00e1 funcionando como se esperaba, junto con una descripci\u00f3n del estado o error. Pueden contener instrucciones sobre c\u00f3mo proceder y resolver los errores que se les presenten.<\/p>\r\n
Ejemplos<\/h3>\r\n
Cuando los usuarios entienden c\u00f3mo funciona la API, es bueno darles ejemplos que muestran ejemplos exitosos de llamadas, respuestas, manejo de errores y otras operaciones que pueden encontrar al usar la API.<\/p>\r\n
Glossary<\/h3>\r\n
En lugar de explicar cada t\u00e9rmino t\u00e9cnico a lo largo de su documentaci\u00f3n, puede enlazar a un glosario que proporciona definiciones de t\u00e9rminos, esquemas y m\u00e1s.<\/p>\r\n<\/div>\r\n
\r\nC\u00f3mo escribir tu primera documentaci\u00f3n API<\/h2>\r\nReconocer al p\u00fablico<\/h3>\r\n
Antes de empezar a crear cualquier tipo de documentaci\u00f3n de la API, debe asegurarse de entender la audiencia prevista para su producto. Debes saber exactamente en qu\u00e9 tipos de usuarios quieres centrarte los beneficios particulares que obtendr\u00e1n de la API, y la forma en que usar\u00e1n su documentaci\u00f3n en el campo.<\/p>\r\n
Es importante recordar que su p\u00fablico potencial para la documentaci\u00f3n de su API normalmente puede dividirse en dos grupos. El primero son los desarrolladores que interactuar\u00e1n con la API y la utilizar\u00e1n activamente que requerir\u00e1 m\u00e1s documentaci\u00f3n a lo largo de las l\u00edneas de tutoriales y ejemplos de c\u00f3digo. El segundo p\u00fablico se compone de l\u00edderes t\u00e9cnicos y gestores de productos que evaluar\u00e1n la API y c\u00f3mo se ajusta a los objetivos empresariales.<\/p>\r\n
Crear un Mapa del recorrido del Usuario<\/h3>\r\n
Cuando los usuarios est\u00e1n interactuando con su documentaci\u00f3n API, pueden estar en una de muchas etapas del recorrido del usuario. Los usuarios que est\u00e9n evaluando primero su API necesitar\u00e1n documentaci\u00f3n para decirles exactamente lo que su API puede hacer y los problemas que resuelve, as\u00ed como definiciones de funciones y puntos finales, y c\u00f3mo su API es diferente de otros proveedores ah\u00ed.<\/p>\r\n
Crear un mapa del recorrido del usuario le permite atender a los usuarios que se encuentran en diferentes etapas y proporcionar una mejor experiencia de desarrollador. Los desarrolladores ser\u00e1n soportados cada paso del camino en lugar de preguntarse qu\u00e9 puede hacer tu API por ellos.<\/p>\r\n
Comenzar con Directrices para Escenarios Comunes<\/h3>\r\n
Hay algunas de las funciones m\u00e1s comunes para las que se utilizar\u00e1 tu API para que puedas crear pautas para estos escenarios. Debes asegurarte de abordar los casos t\u00edpicos de uso de tu API para que los nuevos desarrolladores puedan entender c\u00f3mo utilizar correctamente la API. Cada caso de uso debe tener una secci\u00f3n separada e incluir un mensaje de ejemplo en cada uno de ellos.<\/p>\r\n
Proporcionar directrices para escenarios comunes ayudar\u00e1 a tus desarrolladores a ponerse en marcha sin tener que luchar demasiado por s\u00ed solos. Tambi\u00e9n muestra a los desarrolladores de lo que tu API es capaz y puede persuadirlos de que elijan tu API sobre otros.<\/p>\r\n
A\u00f1adir muestras de c\u00f3digo<\/h3>\r\n
A\u00f1adir muestras de c\u00f3digo a la documentaci\u00f3n de tu API ayuda a los desarrolladores a empezar a probar r\u00e1pidamente tu API y a entender todo su potencial. Cada endpoint debe venir con sus propias muestras de c\u00f3digo para que los desarrolladores puedan adaptar el c\u00f3digo para cumplir con su especificaci\u00f3n exacta y probar las funciones m\u00e1s importantes de los extremos.
\r\nLas muestras de c\u00f3digo muestran a los potenciales desarrolladores c\u00f3mo funciona tu API y les hace m\u00e1s f\u00e1cil empezar porque simplemente pueden copiar y pegar el c\u00f3digo. Puedes incluir muestras de c\u00f3digo en todos los diferentes lenguajes de programaci\u00f3n en los que tu API est\u00e1 disponible.<\/p>\r\n
Mensajes de Error de Llamada y c\u00f3digos de estado<\/h3>\r\n
Los mensajes de error y los c\u00f3digos de estado deben incluirse en tu documentaci\u00f3n porque dicen a tus desarrolladores cuando han realizado o no una llamada API exitosa. Cada mensaje o c\u00f3digo debe incluir una breve descripci\u00f3n de por qu\u00e9 se muestra para que los usuarios puedan entender lo que sucede cuando interact\u00faan con el sistema.<\/p>\r\n
Las descripciones que acompa\u00f1an a los mensajes de error deben construirse con el prop\u00f3sito de mostrar a los usuarios c\u00f3mo resolver los problemas por s\u00ed mismos. Deber\u00edan ser detallados y espec\u00edficos para que los usuarios puedan entender por qu\u00e9 el sistema est\u00e1 devolviendo un error.<\/p>\r\n
Mantiene tu documentaci\u00f3n<\/h3>\r\n
Despu\u00e9s de publicar su documentaci\u00f3n por primera vez, debe asegurarse de revisarla regularmente para mantener el contenido actualizado. No hay nada m\u00e1s desalentador para los posibles usuarios de tu API que una documentaci\u00f3n incompleta o inexacta.
\r\nSi no mantienes la documentaci\u00f3n actualizada y efectiva a lo largo del tiempo, los desarrolladores no podr\u00e1n utilizar tu API y experimentar\u00e1s una disminuci\u00f3n en su adopci\u00f3n. Cada vez que haces una actualizaci\u00f3n o publicas una nueva caracter\u00edstica, esto deber\u00eda reflejarse en la documentaci\u00f3n y ser considerado una parte esencial del env\u00edo de su API.<\/p>\r\n<\/div>\r\n
\r\nMejores pr\u00e1cticas de documentaci\u00f3n API<\/h2>\r\n1. 1. Adoptar el idioma claro<\/h3>\r\n
Al escribir la documentaci\u00f3n de la API, no conocer\u00e1s el nivel de experiencia de los usuarios que la consultar\u00e1n. Por eso, es importante utilizar un lenguaje claro y comprensible para que todos puedan entenderlo.<\/p>\r\n
2. Incluye documentaci\u00f3n de referencia<\/h3>\r\n
La documentaci\u00f3n de referencia para APIs es una lista completa de objetos y m\u00e9todos expuestos por la API, junto con una descripci\u00f3n de c\u00f3mo utilizar cada uno. Esto ense\u00f1a a los desarrolladores todo lo que est\u00e1 disponible y c\u00f3mo funciona.<\/p>\r\n
3. Ejemplos de implementaci\u00f3n<\/h3>\r\n
Con la mayor frecuencia posible debe utilizar ejemplos para el funcionamiento de su API, que se pueden encontrar dentro de cualquier \u00e1rea de referencia de su documentaci\u00f3n. Puede ser cualquier cosa que ilustre el concepto de la API y ayude a los desarrolladores a comenzar con sus propias llamadas API.<\/p>\r\n
4. Pon a alguien a cargo de los documentos<\/h3>\r\n
Necesitas a alguien en tu equipo cuyo trabajo es supervisar la experiencia del desarrollador de la documentaci\u00f3n de tu API. Podr\u00eda ser todo su trabajo si son un escritor t\u00e9cnico o una responsabilidad a tiempo parcial si tambi\u00e9n son un desarrollador.<\/p>\r\n
5. Cubre diferentes tipos y temas<\/h3>\r\n
Debe asegurarse de que la documentaci\u00f3n de su API es completa y que cubre referencias, gu\u00edas y ejemplos. Si algunas \u00e1reas faltan, entonces usar\u00e1s esta informaci\u00f3n para decidir d\u00f3nde enfocar esfuerzos futuros.<\/p>\r\n
6. Incorporar documentaci\u00f3n en procesos<\/h3>\r\n
Su documentaci\u00f3n y su API deben desarrollarse en tandem. Con la evoluci\u00f3n de la API, viene el desarrollo de su documentaci\u00f3n, especialmente junto con las nuevas versiones de funciones. Automatiza todo lo que puedas y ahorra tiempo con tu documentaci\u00f3n.<\/p>\r\n
7. Proporcionar gu\u00edas de inicio r\u00e1pido<\/h3>\r\n
Las gu\u00edas de inicio r\u00e1pido (Quickstart) son la mejor manera de integrar nuevos desarrolladores con tu API y ayudarlos a comenzar a utilizarla. Estas gu\u00edas contienen instrucciones sobre c\u00f3mo usar tu API, as\u00ed como ejemplos de c\u00f3digo que facilitan el acceso a ella<\/p>\r\n
Adem\u00e1s, revisa nuestro blog en Lista de verificaci\u00f3n de documentaci\u00f3n<\/a><\/p>\r\n<\/div>\r\n\r\nEjemplos de documentaci\u00f3n API<\/h2>\r\n
He aqu\u00ed algunos ejemplos de documentaci\u00f3n real de la API que puede utilizar para inspirar sus propios esfuerzos.<\/p>\r\n
GitHub API<\/h3>\r\n
![\"github](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/10\/github_api_documentation.png\")
<\/p>\r\n
La API de GitHub es una API REST<\/a> que los desarrolladores pueden usar para conectarse con la plataforma de GitHub, que es una herramienta de desarrollo colaborativo para proyectos de software. GitHub ofrece documentaci\u00f3n completa de inicio r\u00e1pido para ayudar a los desarrolladores a entender la API y las secciones detalladas para cada aspecto del uso de la API.<\/p>\r\nDocumentos API Twilio<\/h3>\r\n
![\"Twillo](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/10\/twillo_api_documentation.png\")
<\/p>\r\n
La API de Twilio es otra API REST que los desarrolladores pueden usar para conectarse con la plataforma Twilio, una plataforma de participaci\u00f3n de clientes que permite a las empresas comunicarse a escala. La documentaci\u00f3n contiene todo lo que necesita para integrarse con Twilio, incluyendo autenticaci\u00f3n con HTTP y SDKs.<\/p>\r\n
Dropbox API docs<\/h3>\r\n
![\"dropbox](\"https:\/\/document360.com\/wp-content\/uploads\/2022\/10\/dropbox_api_documentation.png\")
<\/p>\r\n
La API de Dropbox permite a los desarrolladores crear integraciones con la plataforma de intercambio de documentos de Dropbox. Ofrece componentes precompilados que ayudan a los usuarios a incrustar componentes de Dropbox, junto con una referencia API para permitir a los desarrolladores construir aplicaciones e integraciones personalizadas. Tambi\u00e9n ofrece varios SDKs oficiales para lenguajes de programaci\u00f3n populares.<\/p>\r\n<\/div>\r\n<\/div>\r\n
Conclusi\u00f3n<\/h2>\r\n
Simplemente construir una API no es suficiente para asegurar la adopci\u00f3n del producto; necesitas proporcionar una documentaci\u00f3n completa de la API para mostrar a tus usuarios potenciales y actuales c\u00f3mo utilizar tu herramienta. Si nadie entiende lo que debe hacer tu API, nadie estar\u00e1 motivado para usarla y perder\u00e1s muchos beneficios potenciales. Incluso si tu API no tiene fines de lucro, querr\u00e1s maximizar el n\u00famero de usuarios a los que est\u00e1s exponiendo tu API.<\/p>\r\n
Al crear la documentaci\u00f3n de tu API, piensa cuidadosamente en tus usuarios potenciales y en los tipos de contenido que les ayudar\u00e1n a sacar el m\u00e1ximo provecho de tu herramienta. Debes cubrir todos los casos de uso m\u00e1s comunes y anticipar los obst\u00e1culos que probablemente encontrar\u00e1n al intentar implementar tu API.<\/p>\r\n
Ofrecer una API es una forma maravillosa de ampliar la funcionalidad de su producto y llegar a grandes grupos de nuevos usuarios. La documentaci\u00f3n es el puente entre tu API y los usuarios finales que usar\u00e1n tu API para alcanzar sus metas.<\/p>\r\n
\r\n\r\nProgramar una demostraci\u00f3n con uno de nuestros expertos para profundizar en Document360<\/p>\r\nReserva una Demo<\/a><\/div>\r\n<\/div>\r\n<\/div>\r\n\r\n\r\n\r\nPreguntas frecuentes<\/h2>\r\n\r\n\t- \r\n
\u00bfQu\u00e9 debe incluirse en la documentaci\u00f3n de la API?<\/a><\/h3>\r\n\r\nLa documentaci\u00f3n de la API debe incluir ejemplos de cada llamada, par\u00e1metro y respuesta a cada llamada. Muestras de c\u00f3digo para lenguajes com\u00fanmente utilizados como Java, JavaScript, PHP y Python deber\u00edan incluirse. Cada petici\u00f3n de API debe ser explicada en detalle en la documentaci\u00f3n, incluyendo muestras de mensajes de error.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
\u00bfCu\u00e1les son los tipos de API? <\/a><\/h3>\r\n\r\nLas APIs se dividen en tres categor\u00edas: Team API simplifica el intercambio de datos entre equipos y sistemas, y APIs asociadas se comparten fuera de la empresa, pero s\u00f3lo con aquellos con los que la organizaci\u00f3n tiene una conexi\u00f3n comercial.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t
- \r\n
\u00bfQui\u00e9n escribe & utiliza la documentaci\u00f3n API? <\/a><\/h3>\r\n
Para el equipo<\/h3>\r\n
Usted puede tener una API que sea interna a su empresa y por lo tanto destinada a ser utilizada \u00fanicamente por miembros de su equipo. El prop\u00f3sito de este tipo de API ser\u00eda agilizar la transferencia de datos entre equipos y sistemas, para que los desarrolladores internos de su empresa sean los encargados de usar esta API.<\/p>\r\n<\/div>\r\n
Para los socios<\/h3>\r\n
Las APIs asociadas se comparten fuera de la organizaci\u00f3n, pero s\u00f3lo con aquellos que tienen una relaci\u00f3n de negocios con la empresa que proporciona la API. S\u00f3lo los clientes autorizados tienen acceso a la API y, como consecuencia, las medidas de seguridad tienden a ser m\u00e1s estrictas con este tipo de API.<\/p>\r\n<\/div>\r\n
Para los usuarios finales<\/h3>\r\n
APIs para usuarios finales o APIs abiertas<\/a> pueden ser utilizadas por cualquier desarrollador sin restricciones. Este tipo de APIs no tienen medidas de autenticaci\u00f3n y autorizaci\u00f3n especialmente estrictas porque los proveedores quieren que la API sea adoptada por tantos desarrolladores como sea posible. A veces este tipo de API estar\u00e1 disponible por una cuota de suscripci\u00f3n que es escalada dependiendo del n\u00famero de llamadas de la API que se est\u00e9n realizando.<\/p>\r\n<\/div>\r\n Naturalmente, como desarrolladores son los que construyen las APIs a menudo tienen la tarea de escribir la documentaci\u00f3n. Desafortunadamente, la documentaci\u00f3n impulsada por el desarrollador a menudo puede ser demasiado t\u00e9cnica porque los desarrolladores est\u00e1n tan cerca del tema. La documentaci\u00f3n escrita por los desarrolladores tambi\u00e9n puede caer en el camino, ya que los desarrolladores est\u00e1n realmente enfocados en construir y mantener la API.<\/p>\r\n Por esta raz\u00f3n, muchas empresas emplean a escritores t\u00e9cnicos profesionales para crear su documentaci\u00f3n API. Los escritores t\u00e9cnicos tienen la capacidad t\u00e9cnica de entender la API y las habilidades creativas para poder escribir contenido atractivo para los usuarios finales que son desarrolladores.<\/p>\r\n Los desarrolladores de la API proporcionan al escritor t\u00e9cnico la informaci\u00f3n que necesitan para poder documentar la API con exactitud. Si faltan partes en la documentaci\u00f3n, los desarrolladores pueden ayudar al escritor t\u00e9cnico a rellenarlas, con el resultado final de tener un documento claro y accesible para su p\u00fablico objetivo.<\/p>\r\n Tambi\u00e9n, revisa nuestro art\u00edculo en C\u00f3mo crear una experiencia encantadora de desarrollador API con la documentaci\u00f3n<\/a><\/em><\/p>\r\n<\/div>\r\n Para los proveedores que quieren ofrecer una API, desarrollar documentaci\u00f3n puede tener muchos beneficios importantes para su organizaci\u00f3n.<\/p>\r\n En primer lugar, la documentaci\u00f3n de API mejora la experiencia del desarrollador. No importa lo bueno que sea tu API si los desarrolladores potenciales no entienden c\u00f3mo usarla. Una buena documentaci\u00f3n de API ayuda a los desarrolladores a entender los diferentes puntos finales que tiene para ofrecer y ejemplos de casos de uso particulares. Cuando mejoras la experiencia del desarrollador incrementas el n\u00famero de usuarios potenciales que puedes atraer a tu producto.<\/p>\r\n Reduce el tiempo de uso interno de desarrolladores internos o socios externos Cuando documentas tu API de forma efectiva, significa que puedes administrar el mantenimiento de tu producto y actualizarlo m\u00e1s r\u00e1pidamente. Con la documentaci\u00f3n API usted sabe exactamente qu\u00e9 debe hacer su producto y c\u00f3mo debe ayudar a los usuarios finales. La documentaci\u00f3n le da una visi\u00f3n m\u00e1s \u00edntima de la API y le permite desplegar actualizaciones m\u00e1s r\u00e1pidas que ser\u00e1n adoptadas por los usuarios.<\/p>\r\n Uno de los principales beneficios de documentaci\u00f3n de la API<\/a> es que ayuda a los usuarios internos y externos a entender la API, para qu\u00e9 se puede usar, y c\u00f3mo se puede desplegar la API para sus propios fines. Si no explica las capacidades potenciales de la API, entonces los nuevos usuarios no sabr\u00e1n c\u00f3mo usarla y experimentar\u00e1n una lenta adopci\u00f3n de productos. Los usuarios Potential de una API usan la documentaci\u00f3n como una manera de tomar la decisi\u00f3n de usar o no su producto.<\/p>\r\n Los miembros del equipo interno de su organizaci\u00f3n pueden referirse a la documentaci\u00f3n de la API cuando quieren familiarizarse con los objetivos de su API. Incluso aquellos que no participaron directamente en la construcci\u00f3n de la API o en la escritura de la documentaci\u00f3n comprender\u00e1n el prop\u00f3sito de la API y podr\u00e1n apoyar el trabajo del equipo de desarrollo de la API.<\/p>\r\n Cuando documentas la API, esto te permite identificar r\u00e1pidamente errores y problemas como resultado de la prueba de la API para documentar todas sus caracter\u00edsticas. Si tu API no funciona como est\u00e1 dise\u00f1ado, esta retroalimentaci\u00f3n puede ser transmitida al equipo de desarrollo de la API, quien puede tomar medidas para solucionar cualquier problema. El resultado es una API m\u00e1s profesional y eficaz que funciona como se esperaba.<\/p>\r\n<\/div>\r\n Un software intuitivo de base de conocimiento para agregar f\u00e1cilmente su contenido e integrarlo en cualquier aplicaci\u00f3n. \u00a1Pru\u00e9balo!<\/p>\r\nComenzar<\/a><\/div>\r\n El contorno de la documentaci\u00f3n de su API tambi\u00e9n es conocido como la descripci\u00f3n. Contiene un resumen de la API y su prop\u00f3sito, y puede informar a los usuarios potenciales sobre los beneficios de usar esta API sobre otros.<\/p>\r\n Los tutoriales forman la parte principal de la API y su prop\u00f3sito es ense\u00f1ar a los usuarios el concepto de la API y c\u00f3mo utilizarla eficazmente. Normalmente contiene gu\u00edas paso a paso para c\u00f3mo integrar la API y c\u00f3mo se ve el funcionamiento apropiado.<\/p>\r\n La autenticaci\u00f3n es la forma en que el proveedor mantiene los datos de la API a salvo para los desarrolladores y usuarios finales, por lo que podr\u00eda tener m\u00faltiples esquemas de autenticaci\u00f3n. La documentaci\u00f3n de la API explica cada m\u00e9todo de autenticaci\u00f3n para que los usuarios entiendan c\u00f3mo acceder a la API.<\/p>\r\n Las definiciones de los endpoints de la API son el punto en el que la API se conecta con el programa de software. El punto en el que la API interact\u00faa con otro sistema se considera el punto final, y puede incluir una URL del servidor o servicio.<\/p>\r\n Las APIs utilizan los c\u00f3digos de estado y de error para informar a los desarrolladores cuando la API no est\u00e1 funcionando como se esperaba, junto con una descripci\u00f3n del estado o error. Pueden contener instrucciones sobre c\u00f3mo proceder y resolver los errores que se les presenten.<\/p>\r\n Cuando los usuarios entienden c\u00f3mo funciona la API, es bueno darles ejemplos que muestran ejemplos exitosos de llamadas, respuestas, manejo de errores y otras operaciones que pueden encontrar al usar la API.<\/p>\r\n En lugar de explicar cada t\u00e9rmino t\u00e9cnico a lo largo de su documentaci\u00f3n, puede enlazar a un glosario que proporciona definiciones de t\u00e9rminos, esquemas y m\u00e1s.<\/p>\r\n<\/div>\r\n Antes de empezar a crear cualquier tipo de documentaci\u00f3n de la API, debe asegurarse de entender la audiencia prevista para su producto. Debes saber exactamente en qu\u00e9 tipos de usuarios quieres centrarte los beneficios particulares que obtendr\u00e1n de la API, y la forma en que usar\u00e1n su documentaci\u00f3n en el campo.<\/p>\r\n Es importante recordar que su p\u00fablico potencial para la documentaci\u00f3n de su API normalmente puede dividirse en dos grupos. El primero son los desarrolladores que interactuar\u00e1n con la API y la utilizar\u00e1n activamente que requerir\u00e1 m\u00e1s documentaci\u00f3n a lo largo de las l\u00edneas de tutoriales y ejemplos de c\u00f3digo. El segundo p\u00fablico se compone de l\u00edderes t\u00e9cnicos y gestores de productos que evaluar\u00e1n la API y c\u00f3mo se ajusta a los objetivos empresariales.<\/p>\r\n Cuando los usuarios est\u00e1n interactuando con su documentaci\u00f3n API, pueden estar en una de muchas etapas del recorrido del usuario. Los usuarios que est\u00e9n evaluando primero su API necesitar\u00e1n documentaci\u00f3n para decirles exactamente lo que su API puede hacer y los problemas que resuelve, as\u00ed como definiciones de funciones y puntos finales, y c\u00f3mo su API es diferente de otros proveedores ah\u00ed.<\/p>\r\n Crear un mapa del recorrido del usuario le permite atender a los usuarios que se encuentran en diferentes etapas y proporcionar una mejor experiencia de desarrollador. Los desarrolladores ser\u00e1n soportados cada paso del camino en lugar de preguntarse qu\u00e9 puede hacer tu API por ellos.<\/p>\r\n Hay algunas de las funciones m\u00e1s comunes para las que se utilizar\u00e1 tu API para que puedas crear pautas para estos escenarios. Debes asegurarte de abordar los casos t\u00edpicos de uso de tu API para que los nuevos desarrolladores puedan entender c\u00f3mo utilizar correctamente la API. Cada caso de uso debe tener una secci\u00f3n separada e incluir un mensaje de ejemplo en cada uno de ellos.<\/p>\r\n Proporcionar directrices para escenarios comunes ayudar\u00e1 a tus desarrolladores a ponerse en marcha sin tener que luchar demasiado por s\u00ed solos. Tambi\u00e9n muestra a los desarrolladores de lo que tu API es capaz y puede persuadirlos de que elijan tu API sobre otros.<\/p>\r\n A\u00f1adir muestras de c\u00f3digo a la documentaci\u00f3n de tu API ayuda a los desarrolladores a empezar a probar r\u00e1pidamente tu API y a entender todo su potencial. Cada endpoint debe venir con sus propias muestras de c\u00f3digo para que los desarrolladores puedan adaptar el c\u00f3digo para cumplir con su especificaci\u00f3n exacta y probar las funciones m\u00e1s importantes de los extremos. Los mensajes de error y los c\u00f3digos de estado deben incluirse en tu documentaci\u00f3n porque dicen a tus desarrolladores cuando han realizado o no una llamada API exitosa. Cada mensaje o c\u00f3digo debe incluir una breve descripci\u00f3n de por qu\u00e9 se muestra para que los usuarios puedan entender lo que sucede cuando interact\u00faan con el sistema.<\/p>\r\n Las descripciones que acompa\u00f1an a los mensajes de error deben construirse con el prop\u00f3sito de mostrar a los usuarios c\u00f3mo resolver los problemas por s\u00ed mismos. Deber\u00edan ser detallados y espec\u00edficos para que los usuarios puedan entender por qu\u00e9 el sistema est\u00e1 devolviendo un error.<\/p>\r\n Despu\u00e9s de publicar su documentaci\u00f3n por primera vez, debe asegurarse de revisarla regularmente para mantener el contenido actualizado. No hay nada m\u00e1s desalentador para los posibles usuarios de tu API que una documentaci\u00f3n incompleta o inexacta. Al escribir la documentaci\u00f3n de la API, no conocer\u00e1s el nivel de experiencia de los usuarios que la consultar\u00e1n. Por eso, es importante utilizar un lenguaje claro y comprensible para que todos puedan entenderlo.<\/p>\r\n La documentaci\u00f3n de referencia para APIs es una lista completa de objetos y m\u00e9todos expuestos por la API, junto con una descripci\u00f3n de c\u00f3mo utilizar cada uno. Esto ense\u00f1a a los desarrolladores todo lo que est\u00e1 disponible y c\u00f3mo funciona.<\/p>\r\n Con la mayor frecuencia posible debe utilizar ejemplos para el funcionamiento de su API, que se pueden encontrar dentro de cualquier \u00e1rea de referencia de su documentaci\u00f3n. Puede ser cualquier cosa que ilustre el concepto de la API y ayude a los desarrolladores a comenzar con sus propias llamadas API.<\/p>\r\n Necesitas a alguien en tu equipo cuyo trabajo es supervisar la experiencia del desarrollador de la documentaci\u00f3n de tu API. Podr\u00eda ser todo su trabajo si son un escritor t\u00e9cnico o una responsabilidad a tiempo parcial si tambi\u00e9n son un desarrollador.<\/p>\r\n Debe asegurarse de que la documentaci\u00f3n de su API es completa y que cubre referencias, gu\u00edas y ejemplos. Si algunas \u00e1reas faltan, entonces usar\u00e1s esta informaci\u00f3n para decidir d\u00f3nde enfocar esfuerzos futuros.<\/p>\r\n Su documentaci\u00f3n y su API deben desarrollarse en tandem. Con la evoluci\u00f3n de la API, viene el desarrollo de su documentaci\u00f3n, especialmente junto con las nuevas versiones de funciones. Automatiza todo lo que puedas y ahorra tiempo con tu documentaci\u00f3n.<\/p>\r\n Las gu\u00edas de inicio r\u00e1pido (Quickstart) son la mejor manera de integrar nuevos desarrolladores con tu API y ayudarlos a comenzar a utilizarla. Estas gu\u00edas contienen instrucciones sobre c\u00f3mo usar tu API, as\u00ed como ejemplos de c\u00f3digo que facilitan el acceso a ella<\/p>\r\n Adem\u00e1s, revisa nuestro blog en Lista de verificaci\u00f3n de documentaci\u00f3n<\/a><\/p>\r\n<\/div>\r\n He aqu\u00ed algunos ejemplos de documentaci\u00f3n real de la API que puede utilizar para inspirar sus propios esfuerzos.<\/p>\r\n La API de GitHub es una API REST<\/a> que los desarrolladores pueden usar para conectarse con la plataforma de GitHub, que es una herramienta de desarrollo colaborativo para proyectos de software. GitHub ofrece documentaci\u00f3n completa de inicio r\u00e1pido para ayudar a los desarrolladores a entender la API y las secciones detalladas para cada aspecto del uso de la API.<\/p>\r\n La API de Twilio es otra API REST que los desarrolladores pueden usar para conectarse con la plataforma Twilio, una plataforma de participaci\u00f3n de clientes que permite a las empresas comunicarse a escala. La documentaci\u00f3n contiene todo lo que necesita para integrarse con Twilio, incluyendo autenticaci\u00f3n con HTTP y SDKs.<\/p>\r\n La API de Dropbox permite a los desarrolladores crear integraciones con la plataforma de intercambio de documentos de Dropbox. Ofrece componentes precompilados que ayudan a los usuarios a incrustar componentes de Dropbox, junto con una referencia API para permitir a los desarrolladores construir aplicaciones e integraciones personalizadas. Tambi\u00e9n ofrece varios SDKs oficiales para lenguajes de programaci\u00f3n populares.<\/p>\r\n<\/div>\r\n<\/div>\r\n Simplemente construir una API no es suficiente para asegurar la adopci\u00f3n del producto; necesitas proporcionar una documentaci\u00f3n completa de la API para mostrar a tus usuarios potenciales y actuales c\u00f3mo utilizar tu herramienta. Si nadie entiende lo que debe hacer tu API, nadie estar\u00e1 motivado para usarla y perder\u00e1s muchos beneficios potenciales. Incluso si tu API no tiene fines de lucro, querr\u00e1s maximizar el n\u00famero de usuarios a los que est\u00e1s exponiendo tu API.<\/p>\r\n Al crear la documentaci\u00f3n de tu API, piensa cuidadosamente en tus usuarios potenciales y en los tipos de contenido que les ayudar\u00e1n a sacar el m\u00e1ximo provecho de tu herramienta. Debes cubrir todos los casos de uso m\u00e1s comunes y anticipar los obst\u00e1culos que probablemente encontrar\u00e1n al intentar implementar tu API.<\/p>\r\n Ofrecer una API es una forma maravillosa de ampliar la funcionalidad de su producto y llegar a grandes grupos de nuevos usuarios. La documentaci\u00f3n es el puente entre tu API y los usuarios finales que usar\u00e1n tu API para alcanzar sus metas.<\/p>\r\n Programar una demostraci\u00f3n con uno de nuestros expertos para profundizar en Document360<\/p>\r\nReserva una Demo<\/a><\/div>\r\n La documentaci\u00f3n de la API debe incluir ejemplos de cada llamada, par\u00e1metro y respuesta a cada llamada. Muestras de c\u00f3digo para lenguajes com\u00fanmente utilizados como Java, JavaScript, PHP y Python deber\u00edan incluirse. Cada petici\u00f3n de API debe ser explicada en detalle en la documentaci\u00f3n, incluyendo muestras de mensajes de error.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t Las APIs se dividen en tres categor\u00edas: Team API simplifica el intercambio de datos entre equipos y sistemas, y APIs asociadas se comparten fuera de la empresa, pero s\u00f3lo con aquellos con los que la organizaci\u00f3n tiene una conexi\u00f3n comercial.<\/p>\r\n<\/div>\r\n<\/li>\r\n\t\u00bfQui\u00e9n escribe la documentaci\u00f3n API?<\/h2>\r\n
Beneficios de la documentaci\u00f3n de API<\/h2>\r\n
Mejora la experiencia del desarrollador de API<\/h3>\r\n
\r\nUna buena documentaci\u00f3n API significa que tus equipos de apoyo y \u00e9xito necesitan pasar menos tiempo incorporando nuevos desarrolladores internos o socios externos. Los nuevos usuarios de su API tienen toda la informaci\u00f3n que necesitan para empezar con su plataforma y configurarse para el \u00e9xito. Cuando los procesos est\u00e1n documentados, elimina la necesidad de que determinados miembros del equipo intervengan.<\/p>\r\nMantenimiento de producto eficiente y actualizaciones m\u00e1s r\u00e1pidas<\/h3>\r\n
Ayuda tanto a los usuarios internos como externos en la integraci\u00f3n de la API y sus capacidades<\/h3>\r\n
El Ir a la Fuente de los Miembros del Equipo para referirse a los Objetivos de la API<\/h3>\r\n
Permite identificar errores r\u00e1pidamente y problemas<\/h3>\r\n
<\/div>\r\n<\/div>\r\nLa estructura de la documentaci\u00f3n de API – Dise\u00f1o y funci\u00f3n<\/h2>\r\n
Una l\u00ednea externa<\/h3>\r\n
Tutoriales<\/h3>\r\n
Autenticaci\u00f3n<\/h3>\r\n
Definici\u00f3n de punto final<\/h3>\r\n
Estado y c\u00f3digos de error<\/h3>\r\n
Ejemplos<\/h3>\r\n
Glossary<\/h3>\r\n
C\u00f3mo escribir tu primera documentaci\u00f3n API<\/h2>\r\n
Reconocer al p\u00fablico<\/h3>\r\n
Crear un Mapa del recorrido del Usuario<\/h3>\r\n
Comenzar con Directrices para Escenarios Comunes<\/h3>\r\n
A\u00f1adir muestras de c\u00f3digo<\/h3>\r\n
\r\nLas muestras de c\u00f3digo muestran a los potenciales desarrolladores c\u00f3mo funciona tu API y les hace m\u00e1s f\u00e1cil empezar porque simplemente pueden copiar y pegar el c\u00f3digo. Puedes incluir muestras de c\u00f3digo en todos los diferentes lenguajes de programaci\u00f3n en los que tu API est\u00e1 disponible.<\/p>\r\nMensajes de Error de Llamada y c\u00f3digos de estado<\/h3>\r\n
Mantiene tu documentaci\u00f3n<\/h3>\r\n
\r\nSi no mantienes la documentaci\u00f3n actualizada y efectiva a lo largo del tiempo, los desarrolladores no podr\u00e1n utilizar tu API y experimentar\u00e1s una disminuci\u00f3n en su adopci\u00f3n. Cada vez que haces una actualizaci\u00f3n o publicas una nueva caracter\u00edstica, esto deber\u00eda reflejarse en la documentaci\u00f3n y ser considerado una parte esencial del env\u00edo de su API.<\/p>\r\n<\/div>\r\nMejores pr\u00e1cticas de documentaci\u00f3n API<\/h2>\r\n
1. 1. Adoptar el idioma claro<\/h3>\r\n
2. Incluye documentaci\u00f3n de referencia<\/h3>\r\n
3. Ejemplos de implementaci\u00f3n<\/h3>\r\n
4. Pon a alguien a cargo de los documentos<\/h3>\r\n
5. Cubre diferentes tipos y temas<\/h3>\r\n
6. Incorporar documentaci\u00f3n en procesos<\/h3>\r\n
7. Proporcionar gu\u00edas de inicio r\u00e1pido<\/h3>\r\n
Ejemplos de documentaci\u00f3n API<\/h2>\r\n
GitHub API<\/h3>\r\n
<\/p>\r\nDocumentos API Twilio<\/h3>\r\n
<\/p>\r\nDropbox API docs<\/h3>\r\n
<\/p>\r\nConclusi\u00f3n<\/h2>\r\n
<\/div>\r\n<\/div>\r\nPreguntas frecuentes<\/h2>\r\n
\r\n\t
\u00bfQu\u00e9 debe incluirse en la documentaci\u00f3n de la API?<\/a><\/h3>\r\n
\u00bfCu\u00e1les son los tipos de API? <\/a><\/h3>\r\n
\u00bfQui\u00e9n escribe & utiliza la documentaci\u00f3n API? <\/a><\/h3>\r\n