Header Ads Widget

Ticker

6/recent/ticker-posts

¿Cuál es la diferencia entre documentación, especificación y definición de API?

 

¿Cuál-es-la-diferencia-entre-definición-API, -especificación-y-documentación

Pocas cosas son tan importantes para una industria como el entendimiento y las definiciones comunes. Sin saber exactamente qué significan los términos específicos de la industria y cómo se aplican a situaciones determinadas, se puede producir poco desarrollo de API de discurso. Parece extraño, entonces, que todavía haya tantos términos en el espacio API que se malinterpretan o se utilizan incorrectamente. El principal de ellos son los conceptos de la documentación de la API ,  la especificación API , y la API Definición . En este artículo, definiremos lo que las personas quieren decir cuando usan estos términos y ofreceremos algunos ejemplos que los representan cuando describimos las API web.

La importancia de la aclaración

La mitad del problema que enfrentamos con estos términos es que a menudo se usan indistintamente. Por ejemplo, si uno buscara en Google “Documentación de API vs. Especificación vs. Definición”, sería difícil encontrar definiciones coherentes de los términos y lo que significan entre sí. Comencemos a desentrañar esta complicada intercambiabilidad y comencemos a formar una imagen relacional más cohesiva de los términos.

Documentación de API

Quizás el término más fácil de definir de los tres es Documentación API . A diferencia de los otros dos, el público consumidor y productor de API en general comprende relativamente bien la documentación de API. Como su nombre lo indica, la documentación de API es simplemente eso: documentación de una API , incluidos ejemplos de cómo los desarrolladores pueden usar cada función y las restricciones que permite la API.

Como cualquier buen recurso, la documentación de API es un enfoque en capas para una comprensión integral. Este enfoque en capas se puede resumir ampliamente en tres niveles: nivel superior, comprensión funcional y comprensión técnica.

Cuando hablamos de documentación de alto nivel , lo que hablamos es una variedad de guías simples o ejemplos sobre cómo funciona la API. Estos puntos de documentación pueden tomar cualquier variedad de formas, desde ejemplos de código y entornos de prueba hasta capturas de pantalla.

Si bien la documentación de nivel superior está estrechamente vinculada a la comprensión funcional y técnica, esto entra mucho más en juego cuando comenzamos a discutir la Especificación y Definición de API, por lo que, por el momento, simplemente piense en este nivel como "comprensión básica para la funcionalidad básica".

El segundo nivel de documentación se considera mejor como comprensión funcional . En esencia, lo que debería hacer una buena documentación en esta etapa es eliminar la abstracción del resto de la documentación. Cuando un consumidor de API lee la documentación, lo hace para una comprensión significativa. Entonces, sorprende a la mayoría de las personas cuando van a leer un documento de documentación de API solo para encontrar que les indica terminología técnica anidada en formatos personalizados o sistemas propietarios. Esta no es una comprensión funcional.

Una buena documentación hace que la niebla no se empañe. “Distribuye el volumen de solicitudes a través de funciones redundantes estabilizadas para un búfer de bucle simulado” no tiene sentido para el usuario medio. "Enruta un gran tráfico a funciones adicionales para equilibrar el uso de recursos" es mucho más eficaz y genera conocimiento funcional de la API.

Finalmente, la documentación de la API incluye una buena fuente de conocimiento técnico . A diferencia de la comprensión funcional, esta sección se ocupa menos del uso funcional de la API y, en cambio, representa una referencia a partir de la cual extraer.

Los números de función, ejemplos de formato, direcciones de repositorio y otros datos similares deben ser fácilmente referenciables en formato de tabla, con suficientes detalles para comprenderlos sin ser abrumadores. La conclusión aquí es simple: la documentación de la API describe, con ejemplos, cómo funciona una API y cómo llamar a esas funciones.

Además: Conozca los beneficios de diseñar su documentación de API en primer lugar

Especificación API

Si bien a menudo se usa indistintamente con la definición, la especificación de API se preocupa mucho más por el comportamiento general de la API y cómo se vincula a otras API. Los dos están estrechamente vinculados: puede derivar documentación de la especificación y viceversa, pero donde divergen hay un conjunto de datos mucho más grande que donde convergen. La especificación de API, en la definición más amplia, es una explicación holística de la API.

Para detallar más específicamente una especificación de API, podemos echar un vistazo a un ejemplo específico. Al observar la especificación Swagger.io , podemos ver un ejemplo amplio de lo que hace una especificación. El ejemplo de swagger combina elementos tanto de la definición de API como de la documentación de API, pero para nuestros propósitos, es un ejemplo bastante decente.

En esta especificación, vemos una variedad de funciones, cómo se llaman y qué hacen. Además, vemos una descripción general de cómo se relacionan entre sí y cómo se pueden usar para aprovechar más la API.

Por ejemplo, observe cómo Swagger define la especificación de manejos para la sesión de Objeto de respuesta de su documento:

Un contenedor para las respuestas esperadas de una operación. El contenedor asigna un código de respuesta HTTP a la respuesta esperada. No se espera que la documentación cubra necesariamente todos los códigos de respuesta HTTP posibles, ya que es posible que no se conozcan de antemano. Sin embargo, se espera que la documentación cubra una respuesta de operación exitosa y cualquier error conocido.

El valor predeterminado se puede utilizar como un objeto de respuesta predeterminado para todos los códigos HTTP que no están cubiertos individualmente por la especificación.

El objeto Respuestas DEBE contener al menos un código de respuesta, y DEBE ser la respuesta para una llamada de operación exitosa.

La especificación continúa definiendo algunas pautas generales en cuanto al resultado esperado y el formato en el mismo, e incluso llega a proporcionar un ejemplo de cómo debería verse la respuesta:

{
  "200": {
    "description": "a pet to be returned",
    "schema": {
      "$ref": "#/definitions/Pet"
    }
  },
  "default": {
    "description": "Unexpected error",
    "schema": {
      "$ref": "#/definitions/ErrorModel"
    }
  }
}

Este es el quid de lo que hace que la especificación sea tan diferente de la documentación. La documentación es esencialmente cómo hacer algo, mientras que la especificación es esencialmente cómo debe funcionar algo y qué debe esperar el usuario.

Además, la Especificación define la filosofía general de diseño, ya sea directa o intrínsecamente a través de las estructuras de ejemplo previstas. ¿La comida para llevar? La especificación de API detalla el comportamiento funcional y esperado de una API, así como la filosofía de diseño fundamental y los tipos de datos admitidos.

Estos son los principales formatos de especificación para las API REST

Definición de API

La Definición de API llena un vacío entre los dos dominios de Especificación de API y Documentación de API. Mientras que la Especificación de API es una comprensión más amplia de la funcionalidad y los resultados esperados de una API, y la Documentación de API es una discusión detallada de cómo funciona la API y cómo utilizarla, la Definición de API está orientada a la legibilidad por máquina.

Aquí llegamos a una encrucijada: la que existe entre el consumo de máquinas y el consumo humano. La documentación de la API atrae al consumo humano , es decir, la documentación de la API está destinada a ser leída, comprendida y utilizada por humanos que utilizan la API y, por lo tanto, está escrita en un formato dirigido a usuarios humanos.

La definición, por otro lado, está más centrada en el concepto de consumo de máquinas , es decir, el uso por máquinas y sistemas automatizados, que en el consumo humano. Como declaró recientemente el evangelista de API Guillame LaForge en el blog de API nórdicas:

“Es fácil mezclar la diferencia entre el formato de definición de API con la documentación de API publicada. Aunque son entidades diferentes, puede generar la documentación a partir de la definición; no se puede negar que las dos están íntimamente vinculadas. Si estuvieran completamente separados, los formatos de definición de API ni siquiera tendrían etiquetas de descripción, ya que el formato probablemente solo se usaría para el consumo de máquinas y no para el consumo humano ". Guillame LaForge

La definición es muy parecida a la documentación y, de hecho, a menudo los desarrolladores experimentados pueden sustituirla. En pocas palabras: las definiciones de API definen la columna vertebral, la organización y la función de una API en un nivel legible por máquina base. Las definiciones de API también son únicas en el sentido de que proporcionan un punto de partida base para derivaciones a otras plataformas: una definición formada, etiquetada y pensada correctamente puede formar el esqueleto de una multitud de derivaciones.

También relacionado: ¿Hasta dónde deben llegar los lenguajes de definición de API?

Comparación de la definición, la especificación y la documentación de la API

La diferencia entre Definición, Especificación y Documentación de API es una doble diferencia entre la legibilidad humana y la máquina, así como el propósito y el objetivo. La definición de API se preocupa mucho más por la definición general de una API y su estructura, mientras que tanto la Especificación como la Documentación se preocupan por informar sobre la API y documentar la API en sí. La gran diferencia con los dos últimos es que la especificación está destinada en gran medida a la legibilidad humana y la comprensión de la "imagen más amplia", mientras que la documentación está destinada a ejemplos directos más específicos y detalles "en el césped".

Con suerte, con un conjunto de definiciones más claro y una línea estricta que las divide, finalmente podemos discutir los temas de API de una manera universal y más clara. Con ese espíritu, si cree que tiene una comprensión diferente de los términos, ¡comente a continuación!

Publicar un comentario

0 Comentarios