Introducción a las Web APIs

1. ¿Qué es una Web API?

Una Web API es una interfaz que permite que dos aplicaciones se comuniquen a través de Internet utilizando, normalmente, el protocolo HTTP.

Una aplicación puede solicitar información o pedir que otra aplicación realice una acción.

2. ¿Cómo funciona una Web API?

El cliente puede ser un navegador, una página web, una aplicación móvil o un programa en Python. El servidor recibe la solicitud, la procesa y devuelve una respuesta.

3. ¿Qué es HTTP?

HTTP significa HyperText Transfer Protocol. Es el protocolo que usan los navegadores, aplicaciones y servidores para comunicarse en la Web. Cuando escribimos una URL en Chrome, normalmente el navegador envía una solicitud HTTP al servidor para pedir un recurso, como una página, una imagen o datos de una API. El servidor procesa esa solicitud y devuelve una respuesta HTTP, que puede contener HTML, JSON, archivos o un mensaje de error. En pocas palabras, HTTP define las reglas de cómo se piden y se entregan recursos por Internet.

Una petición HTTP contiene:

4. La URL identifica el recurso

En una Web API, la URL indica sobre qué recurso queremos trabajar o qué información queremos pedir.

https://timeapi.io/api/Time/current/zone?timeZone=America/Bogota

Recurso: la hora actual de la zona horaria America/Bogota.

Para probarlo: copia esta URL y pégala en el navegador de tu preferencia, por ejemplo en Chrome. Luego presiona Enter para ver qué respuesta devuelve la API.

Botón: abre ese recurso y muestra la respuesta de la API con la fecha y hora actual de Bogotá.

https://timeapi.io/api/Time/current/zone?timeZone=Europe/Madrid

Recurso: la hora actual de la zona horaria Europe/Madrid.

Botón: abre ese recurso y muestra la respuesta de la API con la fecha y hora actual de Madrid.

5. Los métodos HTTP indican la acción

6. ¿Qué es JSON?

JSON significa JavaScript Object Notation. Es un formato de texto usado para representar datos de una manera ordenada y fácil de compartir entre aplicaciones.

Aunque nació relacionado con JavaScript, hoy JSON se usa en muchos lenguajes de programación como Python, Java, PHP, C# y otros. Por eso es muy común encontrarlo en Web APIs: el servidor puede enviar datos en JSON y diferentes aplicaciones pueden leerlos sin importar con qué tecnología fueron creadas.

JSON es fácil de leer porque cada dato viene acompañado por una etiqueta, llamada clave. Esa clave nos ayuda a entender qué significa el valor que estamos viendo.

Por ejemplo, si una API devuelve "ciudad": "Bogotá", la clave ciudad nos indica que el valor "Bogotá" representa una ciudad. Si devuelve "hora": "14:30", la clave hora nos indica que ese valor representa una hora.

{
  "id": 15,
  "nombre": "Guillermo",
  "ciudad": "Bogotá"
}

En este ejemplo, el JSON representa una persona con tres datos: su identificador, su nombre y su ciudad.

7. ¿Qué es REST?

REST significa Representational State Transfer. En español se puede entender como transferencia de estado representacional, aunque en la práctica casi siempre se usa la sigla REST.

Para entenderlo, pensemos en tres palabras: recurso, estado y representación. Un recurso es algo sobre lo que queremos consultar o actuar, por ejemplo /estudiantes/123. El estado son los datos actuales de ese recurso: su nombre, su curso, su edad u otra información guardada en ese momento.

La representación es la forma en que ese estado viaja entre el servidor y el cliente. En una Web API, esa representación normalmente se envía en JSON. Por ejemplo, el estado de un estudiante puede representarse así:

{
  "id": 123,
  "nombre": "Laura",
  "curso": "APIs"
}

Entonces, transferencia de estado representacional significa que cliente y servidor se comunican transfiriendo representaciones del estado de los recursos. Cuando hacemos GET /estudiantes/123, el servidor devuelve una representación del estado actual de ese estudiante. Si luego esos datos cambian, la representación que recibimos también puede cambiar.

REST es un estilo para diseñar Web APIs de forma ordenada. En una API REST, la URL identifica el recurso y el método HTTP indica qué acción queremos realizar sobre ese recurso.

Ejemplo:

GET https://crudcrud.com/api/2b666dbf7e594bfea2455b1070f32ad6/estudiantes
→ obtener la lista de estudiantes

POST https://crudcrud.com/api/2b666dbf7e594bfea2455b1070f32ad6/estudiantes
→ crear un nuevo estudiante

DELETE https://crudcrud.com/api/2b666dbf7e594bfea2455b1070f32ad6/estudiantes/123
→ eliminar el estudiante 123

La URL identifica el recurso. El método cambia la acción que queremos ejecutar sobre ese recurso.

8. Códigos de respuesta HTTP

9. API Key

Muchas Web APIs requieren una API Key. Es una clave que identifica quién está usando el servicio.

Sirve para controlar acceso, límites de uso, cuotas y cobros.

10. Ejercicio 1: Probar APIs con Hoppscotch

Hoppscotch es una herramienta web que permite probar Web APIs sin programar. Desde allí podemos elegir el método HTTP, escribir una URL, enviar datos en el Body y leer la respuesta que devuelve el servidor.

URL de Hoppscotch: https://hoppscotch.io

CrudCrud.com crea una API REST temporal para practicar operaciones CRUD: crear, leer, actualizar y eliminar datos. La API dura 24 horas y permite hasta 100 interacciones, suficiente para hacer pruebas en clase sin construir un servidor propio.

Cuando entras a crudcrud.com, la página te entrega un código único para tu API. Si quieres abrir una API nueva, no tienes que escribir una URL completa: simplemente ve a CrudCrud.com y el sitio generará un nuevo endpoint para ti.

URL reservada: https://crudcrud.com/api/2b666dbf7e594bfea2455b1070f32ad6

Recurso para practicar: https://crudcrud.com/api/2b666dbf7e594bfea2455b1070f32ad6/estudiantes

Pasos generales

1. Seleccionar el método HTTP.
2. Escribir la URL.
3. Agregar Body si el método lo requiere.
4. Presionar Send.
5. Leer la respuesta JSON.

11. Ejemplo GET

Con GET pedimos información al servidor. En este caso vamos a consultar la colección de estudiantes en nuestra API temporal de CrudCrud.

GET https://crudcrud.com/api/2b666dbf7e594bfea2455b1070f32ad6/estudiantes

Este ejemplo se puede probar directamente en el navegador: copia la URL, pégala en Chrome y presiona Enter. El navegador hará una petición GET y mostrará la respuesta de la API.

Respuesta esperada:

[]

Si todavía no hemos creado estudiantes, la respuesta será una lista vacía. Después de hacer un POST, esta misma URL devolverá los estudiantes guardados.

12. Ejemplo POST

Con POST enviamos información al servidor para crear un nuevo recurso. Este ejemplo no se hace pegando la URL en el navegador, porque necesitamos enviar un Body en formato JSON. Lo haremos en Hoppscotch.

POST https://crudcrud.com/api/2b666dbf7e594bfea2455b1070f32ad6/estudiantes

Cómo hacerlo en Hoppscotch

1. Abrir Hoppscotch.
2. Seleccionar el método POST.
3. Pegar la URL del recurso /estudiantes.
4. Agregar el header Content-Type: application/json.
5. En la pestaña Body, escribir el JSON del estudiante.
6. Presionar Send.

Header:

Content-Type: application/json

Body en formato JSON:

{
  "nombre": "Laura",
  "curso": "APIs",
  "edad": 16
}

Respuesta esperada:

{
  "_id": "id_generado_por_crudcrud",
  "nombre": "Laura",
  "curso": "APIs",
  "edad": 16
}

CrudCrud agrega automáticamente una propiedad _id. Ese identificador sirve para consultar, actualizar o eliminar ese estudiante específico.

13. Ejemplo DELETE

Con DELETE pedimos al servidor eliminar un recurso específico. Para hacerlo necesitamos el _id del estudiante que creó CrudCrud cuando hicimos el POST.

DELETE https://crudcrud.com/api/2b666dbf7e594bfea2455b1070f32ad6/estudiantes/id_generado_por_crudcrud

Cómo hacerlo en Hoppscotch

1. Primero crea un estudiante con POST.
2. Copia el valor de _id que devuelve CrudCrud.
3. Selecciona el método DELETE.
4. Pega la URL y reemplaza id_generado_por_crudcrud por el _id real.
5. Presiona Send.

Ejemplo con un identificador ficticio:

DELETE https://crudcrud.com/api/2b666dbf7e594bfea2455b1070f32ad6/estudiantes/66a123456789abcdef123456

14. Consumir una Web API desde Python

El mismo GET se puede hacer desde Python usando la librería requests.

import requests

url = "https://jsonplaceholder.typicode.com/posts/1"

respuesta = requests.get(url)

datos = respuesta.json()

print(datos)

Python hace lo mismo que Hoppscotch: construye una petición HTTP, la envía y lee la respuesta.

15. Resumen final

Una Web API permite que aplicaciones ubicadas en diferentes computadores se comuniquen por Internet.