1. Introducción
en la intersección de varios dominios (estadística, programación, inteligencia artificial) la capacidad de transmitir metodologías e ideas complejas se vuelve crucial. Por lo tanto, la habilidad para manejar conceptos integrales de API es esencial para una comunicación efectiva dentro del equipo.
En primer lugar, fomenta la colaboración entre los miembros del equipo y las partes interesadas. Los proyectos de ciencia de datos (DS) a menudo involucran equipos multidisciplinarios compuestos no solo por especialistas en datos, sino también desarrolladores de software, analistas de negocios, gerentes de proyectos, etc. Las API bien documentadas sirven como puente entre todos ellos, permitiendo que estos diversos grupos comprendan y utilicen los modelos y herramientas de DS correctamente.
En segundo lugar, la documentación API de alta calidad mejora la reproducibilidad y podría reducir el tiempo de incorporación de los recién llegados. En DS, donde los modelos y análisis deben validarse y replicarse, una documentación API clara garantiza que otros puedan seguir los mismos procesos, utilizar los mismos datos y lograr resultados consistentes. Esto es particularmente importante en el desarrollo de la toma de decisiones basada en datos.
Finalmente, a medida que la ciencia de datos se integra cada vez más en las estrategias comerciales, las API bien documentadas pueden mejorar la escalabilidad de las soluciones de datos y simplificar el proceso de trabajo con datos. Por ejemplo, las API pueden desempeñar un papel importante en la recopilación de datos para proyectos, permitiendo la creación rápida de prototipos y el desarrollo de aplicaciones que dependen de información actualizada. Al aprovechar las API para la recopilación de datos de fuentes como países REST (ver Caso 6.1), los científicos de datos pueden centrarse en el análisis en lugar de en la adquisición de datos.
En esta publicación haremos:
Explore brevemente qué es una API y su propósito en el desarrollo de software. Conoce los principales componentes de la API REST. Describir los formatos más comunes y proporcionar casos prácticos de llamadas y respuestas API. Resuma cómo debería verse una buena documentación de API, con información sobre puntos finales, parámetros y respuestas.
2. ¿Qué es API?
Una API (Interfaz de programación de aplicaciones) comprende un conjunto de métodos mediante los cuales diferentes programas se comunican entre sí e intercambian datos. Esencialmente, es un intermediario que permite que aplicaciones, dispositivos, servidores y otros sistemas intercambien información, mientras oculta los procesos dentro de cada sistema entre sí.
Imagine una biblioteca con una gran colección de libros y un bibliotecario que sabe dónde encontrar el libro exacto que necesita un determinado lector. Aquí podemos referirnos al bibliotecario como una API que simplifica el proceso de acceso a la información, evitando que los lectores (nuestro "frontend") pierdan tiempo buscando en todo el catálogo de libros (nuestro "backend"), permitiéndoles centrarse solo en su solicitud específica. Además, si los lectores necesitan otros libros, pueden repetir el proceso de envío de solicitud a la API nuevamente.
Esta analogía resalta el papel de la API como intermediario entre el usuario y la fuente de datos, proporcionando un acceso conveniente y eficiente a la información.
Un caso especial de API es una API REST que sigue los conceptos de la arquitectura REST (REpresentational State Transfer). Las API REST reciben el nombre de estándar de la industria porque son livianas, flexibles y utilizan formatos de datos comunes como JSON o XML.
3. Componentes de la API REST
Cada uno de los componentes de la API REST a continuación desempeña un papel vital en la organización de las interacciones cliente-servidor.
3.1. Recursos
Un recurso es cualquier entidad a la que se puede acceder a través de la API. Cada recurso tiene un identificador único (URI), por ejemplo:
https://api.thecatapi.com/v1/images/search?size=med
Aquí, imágenes es una colección de imágenes de gatos de la página web The Cat API.[1]y search?size=med es el filtro para ver solo imágenes de tamaño mediano.
3.2. Métodos HTTP
Los métodos HTTP se utilizan para interactuar con los recursos:
GET: recupera datos sobre un recurso; POST: crea un nuevo recurso; PUT: actualiza un recurso; PATCH: actualización parcial de un recurso; ELIMINAR: eliminar un recurso.
3.3. Solicitudes y respuestas
Los datos se intercambian entre el cliente y el servidor a través de solicitudes y respuestas HTTP. En la mayoría de los casos, se utiliza el formato JSON porque es fácil de leer y es compatible con la gran mayoría de lenguajes de programación.
3.4. Encabezados HTTP
Los encabezados se utilizan para transmitir información adicional, como el tipo de contenido (Content-Type) o los parámetros de autenticación (Autorización).
3.5. Códigos de respuesta HTTP
Cada solicitud HTTP recibe una respuesta con un código de estado específico:
200 OK: solicitud exitosa; 201 Creado: recurso creado exitosamente; 400 Solicitud incorrecta: error de solicitud del cliente; 401 No autorizado: falta de derechos de acceso; 404 No encontrado: recurso no encontrado; 500 Error interno del servidor: error del lado del servidor.
4. Clientes API
Clientes API como Postman o Bruno[2]Simplifique la interacción API proporcionando un espacio de trabajo dedicado para enviar solicitudes y gestionar respuestas. En lugar de utilizar herramientas de línea de comandos o escribir código como hicimos en el Caso 6.1, estos agentes ofrecen interfaces visuales y funciones de automatización que aceleran los flujos de trabajo.
Por lo tanto, en el Caso 6.2, consideraremos usar Bruno para interactuar con la página web JokeAPI.[3]. El uso de Bruno simplifica el complejo proceso de interacción entre diferentes sistemas de software. Sin Bruno y otros clientes API, los desarrolladores tendrían que construir manualmente cada solicitud HTTP y procesar cada respuesta sin procesar desde cero.
5. Consejos para crear una buena documentación API
Crear documentación de API eficaz es fundamental para garantizar que los usuarios puedan comprender y utilizar fácilmente su API. Aquí hay algunos consejos clave a tener en cuenta:
5.1. Priorice la simplicidad, la claridad y la coherencia
Evite la jerga técnica y la terminología inconsistente. En su lugar, utilice un lenguaje lo suficientemente claro y sencillo que sea fácil de seguir. Si es necesario, establezca una guía de estilo para mantener la uniformidad en toda su documentación. Aquí puede indicar las reglas principales que se utilizan en toda su documentación, por ejemplo, cómo formatear los fragmentos de código, instantáneas, el tono de voz preferido, etc.
5.2. Incluir detalles completos
La documentación API completa debe abarcar varios elementos esenciales; en particular, una página típica con un método API incluye:
Una breve descripción (1 o 2 frases) que describa claramente el objetivo principal del criterio de valoración. La sintaxis de la solicitud: una descripción general de la llamada API. Métodos de autenticación: detalle los procesos de autenticación necesarios para acceder a la API de forma segura. Parámetros y tipos de datos: especifique los parámetros requeridos y sus tipos de datos correspondientes para las solicitudes. Ejemplos de solicitudes: proporcione ejemplos de solicitudes correctas y solicitudes con error para ilustrar cómo utilizar la API de forma eficaz.
6. Casos prácticos
Caso 6.1: Realizar una solicitud a una API RESTful usando Python
La recopilación de datos a nivel nacional es esencial para comprender las tendencias globales, regionales o nacionales, lo que permite una toma de decisiones informada para gobiernos, empresas e investigadores individuales. Cuando se trabaja con datos de países como el sitio web de países REST[4], los científicos de datos pueden obtener información sobre países a través de una API RESTful para obtener áreas, población y demonios de manera eficiente sin extraer manualmente toneladas de datos web. El siguiente código recupera y muestra datos sobre países de Centroamérica:
solicitudes de importación import json url = 'https://restcountries.com/v3.1/subregion/Central America/?fields=name,area,population,demonyms' respuesta = request.get(url) jdata = respuesta.json() formatted_json = json.dumps(jdata, indent=4) print(formatted_json)
Las regiones geográficas se definen utilizando la metodología de la ONU.[5]. También puede filtrar la respuesta en ciertos campos.[6]: en nuestro caso, son nombre, área, cantidad de población y demonios.
El resultado se proporciona como un archivo JSON legible por humanos:
[ { "name": { "common": "Honduras", "official": "Republic of Honduras", "nativeName": { "spa": { "official": "Repu00fablica de Honduras", "common": "Honduras" } } }, "demonyms": { "eng": { "f": "Hondureño", "m": "Hondureño" }, "fra": { "f": "Hondurienne", "m": "Hondurien" } }, "area": 112492.0, "population": 9892632 }, { "name": { "common": "Costa Rica", "official": "Republic of Costa Rica", "nativeName": { "spa": { "official": "Repu00fablica de Costa Rica", "common": "Costa Rica" } } }, "demonyms": { "eng": { "f": "Costaricense", "m": "Costaricain" }, "fra": { "f": "Costaricaine", "m": "Costaricain" } }, "area": 51100.0, "población": 5309625 }, { "name": { "common": "Guatemala", "official": "Republic of Guatemala", "nativeName": { "spa": { "official": "Repu00fablica de Guatemala", "common": "Guatemala" } } }, "demonyms": { "eng": { "f": "Guatemalan", "m": "Guatemalan" }, "fra": { "f": "Guatu00e9maltu00e8que", "m": "Guatu00e9maltu00e8que" } }, "area": 108889.0, "population": 18079810 }, { "name": { "common": "Panamá", "official": "Republic of Panama", "nativeName": { "spa": { "official": "Repu00fablica de Panamu00e1", "common": "Panamu00e1" } } }, "demonyms": { "eng": { "f": "Panamá", "m": "Panamá" }, "fra": { "f": "Panamáu00e9enne", "m": "Panamáu00e9en" } }, "área": 75417.0, "población": 4064780 }, { "nombre": { "common": "Nicaragua", "oficial": "República de Nicaragua", "nativeName": { "spa": { "official": "Repu00fablica de Nicaragua", "common": "Nicaragua" } } }, "demonyms": { "eng": { "f": "Nicaraguan", "m": "Nicaraguan" }, "fra": { "f": "Nicaraguayenne", "m": "Nicaraguayen" } }, "area": 130373.0, "population": 6803886 }, { "name": { "common": "Belize", "official": "Belize", "nativeName": { "bjz": { "official": "Belize", "common": "Belize" }, "eng": { "official": "Belice", "common": "Belize" }, "spa": { "official": "Belice", "common": "Belice" } } }, "demonyms": { "eng": { "f": "Belizean", "m": "Belizean" }, "fra": { "f": "Bu00e9lizienne", "m": "Bu00e9lizien" } }, "área": 22966.0, "población": 417634 }, { "name": { "common": "El Salvador", "official": "Republic of El Salvador", "nativeName": { "spa": { "official": "Repu00fablica de El Salvador", "common": "El Salvador" } } }, "demonyms": { "eng": { "f": "Salvadoreño", "m": "Salvadoreño" }, "fra": { "f": "Salvadorienne", "m": "Salvadorien" } }, "area": 21041.0, "población": 6029976 } ]
Caso 6.2: Realizar una solicitud a JokeAPI usando Bruno
JokeAPI es una API REST gratuita y de código abierto que ofrece chistes en varios formatos, por ejemplo, JSON, XML, YAML o texto sin formato.[3].
Abra Bruno y seleccione Colecciones → + Crear colección. Seleccione un nombre para su colección, por ejemplo, API de muestra. La colección creada se muestra en el panel izquierdo. Para crear una solicitud, haga clic en… → Nueva solicitud. Seleccione el tipo de solicitud (HTTP) y especifique su nombre, por ejemplo, joke_request. En la celda de la URL, seleccione el método (GET) e ingrese el punto final https://v2.jokeapi.dev/joke/Any?blacklistFlags=religious,political,racist,sexist&type=single.
La URL se creó en función de las preferencias que usted seleccionó en el sitio web de JokeAPI. En nuestro ejemplo, elegimos cualquier categoría de chiste, excepto nsfw, religiosos, políticos, racistas y sexistas (fueron marcados y puestos en la lista negra). Los parámetros que seleccionamos en el sitio web y copiamos aparecieron en la solicitud después del? como una cadena de consulta a la URL del punto final en el campo GET, separados por & entre sí. También aparecerán en una tabla en la pestaña Parámetros. Haga clic en Enviar, espere un poco… y recibirá como respuesta un chiste no tan malo ("La generación de números aleatorios es demasiado importante para dejarla al azar"). Preste atención al estado de la solicitud: es 200 OK, lo que significa éxito.
Es importante tener en cuenta que en este ejemplo, no necesitábamos una clave API para acceder a nuestro recurso API REST. De lo contrario, tendríamos que pasarlo como encabezado en una pestaña de Encabezados separada.
Caso 6.3: Realizar una solicitud a las API abiertas de la NASA con clave API
El APOD (Astronomy Picture of the Day) de la NASA es un popular servicio que proporciona a los usuarios acceso a la foto o vídeo diario relacionado con la astronomía, junto con una descripción.[7].
Hagamos brevemente un ejemplo de muestra de documentación de la API APOD de la NASA basándonos en los consejos del quinto párrafo.
Documentación de la API APOD de la NASA
Descripción: Esta API permite a los usuarios recuperar imágenes o videos para fechas o rangos específicos o simplemente seleccionados al azar del sitio web APOD NASA.
Sintaxis de solicitud: OBTENER https://api.nasa.gov/planetary/apod
Métodos de autenticación: para acceder a la API de APOD, debe incluir una clave API en su solicitud. Para obtener una clave API gratuita, debe suscribirse en https://api.nasa.gov/. Esta clave debe incluirse como parámetro de consulta en la solicitud.
Parámetros y tipos de datos: consulte la siguiente tabla
* — parámetros requeridos
Ejemplos de solicitud
Solicitud correcta con estado 200 OK
OBTÉN https://api.nasa.gov/planetary/apod?api_key=
{ "copyright": "Simone Curzi", "date": "2026-05-18", "explanation": "La galaxia espiral NGC 3169 parece estar deshaciéndose como un ovillo de hilo cósmico. Se encuentra a unos 70 millones de años luz de distancia, al sur de la brillante estrella Regulus, hacia la débil constelación de Sextans. Los brazos espirales enrollados se extienden formando amplias colas de marea como NGC 3169 (izquierda) y sus vecinas. NGC 3166 interactúa gravitacionalmente. Eventualmente las galaxias se fusionarán en una sola, un destino común incluso para las galaxias brillantes en el universo local. Los arcos y columnas estelares dilatados son indicaciones claras de las interacciones gravitacionales en curso a lo largo de la profunda y colorida fotografía del grupo de galaxias. El marco telescópico abarca unos 20 minutos de arco o unos 400.000 años luz a la distancia estimada del grupo, e incluye a NGC 3165, más pequeña y azulada. a la derecha también se sabe que NGC 3169 brilla en todo el espectro, desde radio hasta rayos X, albergando un núcleo galáctico activo que es el sitio de un agujero negro supermasivo.", "hdurl": "https://apod.nasa.gov/apod/image/2605/ngc3169_ngc3166_ngc3165.jpg", "media_type": "image", "service_version": "v1", "title": "Desentrañando NGC 3169", "url": "https://apod.nasa.gov/apod/image/2605/ngc3169_ngc3166_ngc3165px1024.jpg" }
Solicitud correcta con estado 200 OK para un rango de fechas
OBTÉN https://api.nasa.gov/planetary/apod?start_date=2025-03-03&end_date=2025-03-05&api_key=
[ { "date": "2025-03-03", "explanation": "Hay un nuevo módulo de aterrizaje en la Luna. Ayer, Blue Ghost de Firefly Aerospace ejecutó el primer alunizaje comercial exitoso. Durante su misión planificada de 60 días, Blue Ghost desplegará varios instrumentos científicos encargados por la NASA, incluido PlanetVac, que captura el polvo lunar después de crear un pequeño torbellino de gas. Blue Ghost también albergará el telescopio LEXI que captura imágenes de rayos X de la Luna. Los datos de la magnetosfera de la Tierra LEXI deberían permitir una mejor comprensión de cómo el campo magnético de la Tierra protege a la Tierra del viento y las llamaradas del Sol. En la foto, la sombra del módulo de aterrizaje Blue Ghost es visible en la superficie lunar llena de cráteres, mientras que el orbe brillante del planeta Tierra flota justo sobre el horizonte. Los objetivos de los futuros módulos de aterrizaje robóticos Blue Ghost incluyen el apoyo a los astronautas lunares en el programa Artemis de la NASA, actualmente programado para llevar humanos a la Luna. 2027.", "hdurl": "https://apod.nasa.gov/apod/image/2503/BlueGhostShadow_Firefly_4096.jpg", "media_type": "image", "service_version": "v1", "title": "Fantasma azul en la luna", "url": "https://apod.nasa.gov/apod/image/2503/BlueGhostShadow_Firefly_960.jpg" }, { "copyright": "Valerio Minato", "date": "2025-03-04", "explanation": "¿Por qué esta Luna se ve tan inusual? Una razón clave es su vivo color rojo. El color es causado por la desviación de la luz azul por la atmósfera de la Tierra, la misma razón por la que el cielo diurno parece azul. La Luna también aparece inusualmente distorsionada. Su extraña estructura es un efecto óptico que surge de capas en la atmósfera de la Tierra que refractan la luz de manera diferente debido a cambios repentinos diferencias en temperatura o presión. Una tercera razón por la que la Luna parece tan inusual es que, por casualidad, hay un avión volando delante. La pintoresca Luna gibosa fue capturada hace unas dos semanas sobre Turín, Italia. Nuestro familiar orbe celeste flotante fue parte de una inusual alineación cuádruple que incluía dos estructuras terrestres históricas: la Sacra di San Michele en la colina cercana y la Basílica de Superga, justo más allá. "hdurl": "https://apod.nasa.gov/apod/image/2503/QuadMoon_Minato_960.jpg", "media_type": "image", "service_version": "v1", "title": "Una alineación cuádruple sobre Italia", "url": "https://apod.nasa.gov/apod/image/2503/QuadMoon_Minato_960.jpg" }, { "copyright": "Todd Anderson", "date": "2025-03-05", "explanation": "A la derecha, vestidas de azul, están las Pléyades. También conocidas como las Siete Hermanas y M45, las Pléyades son uno de los cúmulos abiertos más brillantes y fácilmente visibles del cielo. Las Pléyades contienen más de 3.000 estrellas, están a unos 400 años luz de distancia y solo 13 años luz de diámetro. Alrededor de las estrellas hay una espectacular nebulosa de reflexión azul. Una leyenda común es que una de las estrellas más brillantes se desvaneció desde que se nombró al cúmulo. A la izquierda, brillando en rojo, está la Nebulosa de California. Llamada así por su forma, la Nebulosa de California es mucho más tenue y, por lo tanto, más difícil de ver que las Pléyades. También conocida como NGC 1499, esta masa de gas de hidrógeno brillante de color rojo se encuentra a unos 1.500 años luz de distancia. ambos Una inspección cuidadosa de la imagen profunda también revelará la región de formación estelar IC 348 y la nube molecular LBN 777 (la Nebulosa del Águila Bebé: Salto alrededor del Universo: Generador APOD aleatorio), "hdurl": "https://apod.nasa.gov/apod/image/2503/California2Pleiades_Anderson_9953.jpg", "media_type": "image", "service_version": "v1", "title": "Seven. Hermanas versus California", "url": "https://apod.nasa.gov/apod/image/2503/California2Pleiades_Anderson_960.jpg" } ]
Solicitud de error con estado 400 Solicitud incorrecta
OBTÉN https://api.nasa.gov/planetary/apod?date=2023-03-01&end_date=2023-03-01&api_key=
{ "code": 400, "msg": "Solicitud incorrecta: se pasó una combinación de campos no válida. Los campos de solicitud permitidos para el método apod son 'concept_tags', 'date', 'hd', 'count', 'start_date', 'end_date', 'thumbs'", "service_version": "v1" }
7. Conclusión
Saber leer (y quizás escribir) la documentación de la API no es sólo una tarea técnica; es un componente vital de la práctica exitosa del análisis de datos, ya que mejora la colaboración, la reproducibilidad, la adopción y la escalabilidad. Al priorizar la documentación clara y detallada, los científicos de datos pueden asegurarse de que se sentirán cómodos trabajando con herramientas modernas.
Por ejemplo, muchos científicos de datos ahora utilizan herramientas como Claude Code, un agente de codificación de inteligencia artificial. Con Claude Code, sus archivos se almacenan localmente en su computadora y el asistente de IA los lee desde allí y envía el contenido del texto a la API de Anthropic para su procesamiento. Vale la pena señalar que la documentación completa de la API de Claude describe todos los matices de su funcionamiento. Específicamente, la API de Claude es una API RESTful en https://api.anthropic.com que proporciona acceso programático a los modelos de Claude y a los agentes de Claude administrados.[8]. Con suerte, después de leer esta publicación comprenderás un poco mejor esta (y otras) documentación 🙂
¡Gracias por leer!
Lista de referencias
La página web Cat API: https://thecatapi.com/ Documentación de Bruno: https://docs.usebruno.com/introduction/getting-started Página web de JokeAPI: https://jokeapi.dev/ Países REST v3.1: https://restcountries.com/ Metodología UNSD: Códigos estándar de país o área para uso estadístico (M49) Lista de campos en la página GitLab del proyecto: https://gitlab.com/restcountries/restcountries/-/blob/master/FIELDS.md API abiertas de la NASA: https://api.nasa.gov/ Claude API Docs: descripción general: https://platform.claude.com/docs/en/api/overview