La app que nunca ve la base
Una app de soporte técnico muestra en el móvil los avisos abiertos. No se conecta a la base de datos.
Envía una petición web a un pequeño servidor. El servidor ejecuta la consulta y devuelve las filas.
Ese servidor es una API web. Casi todas las apps que usas hablan así con sus datos.
Al terminar esta lección
Nota
Puedo leer y escribir filas por HTTP.
Palabras clave
| Palabra | Qué significa | Ejemplo |
|---|---|---|
| API | una forma de que un programa pida datos a otro | |
| Endpoint | la dirección web de una tabla o de una acción | /tickets |
| Método HTTP | el verbo de una petición: leer, añadir, cambiar o quitar | GET |
| JSON | texto que escribe las filas como listas y pares nombre-valor | |
| Código de estado | un número que dice cómo fue una petición | 404 |
| Filtro | una prueba en la dirección que elige qué filas vuelven | status=eq.open |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Una API pone una tabla en la web
En este laboratorio, una herramienta llamada PostgREST convierte cada tabla en una dirección web. /tickets es la tabla tickets.
Envías una petición con curl. El servidor responde con filas escritas en JSON: una lista entre corchetes, con cada fila entre llaves.
Primero crea una tabla de avisos con psql, el cliente de la base. Ejecuta esto en orden.
Dar a psql la contraseña
export PGPASSWORD=shopSe muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Empezar de cero
psql -h db -U shop -c "drop table if exists tickets"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Crear la tabla tickets
psql -h db -U shop -c "create table tickets (id serial primary key, title text not null, status text not null default 'open', priority int not null)"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Añadir cuatro avisos
psql -h db -U shop -c "insert into tickets (title, status, priority) values ('Impresora atascada', 'open', 2), ('Sin wifi en la sala 4', 'open', 3), ('Cambiar contrasena', 'closed', 1), ('Portatil no arranca', 'open', 3)"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Decir a la API que vuelva a mirar
psql -h db -U shop -c "notify pgrst, 'reload schema'"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Leer la tabla entera
curl -s -w "\n" "http://api:3000/tickets?order=id"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
La dirección dice qué filas quieres
Todo lo que va tras el ? es un filtro, como un WHERE. status=eq.open significa que el estado es open. priority=gte.3 significa que la prioridad es 3 o más.
select=id,title elige columnas. order=priority.desc ordena. limit=2 recorta la lista. Únelos con &.
Pon toda la dirección entre comillas dobles, o el shell leerá el &.
Solo los avisos abiertos
curl -s -w "\n" "http://api:3000/tickets?status=eq.open&order=id"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Dos columnas, solo los urgentes
curl -s -w "\n" "http://api:3000/tickets?priority=gte.3&select=id,title&order=id"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Los dos más urgentes
curl -s -w "\n" "http://api:3000/tickets?order=priority.desc,id&limit=2"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Ejemplo resuelto: SQL y HTTP, lado a lado
| SQL | Método HTTP | Dirección y cuerpo |
|---|---|---|
| SELECT ... WHERE | GET | /tickets?status=eq.open |
| INSERT INTO | POST | /tickets, con la fila nueva en JSON |
| UPDATE ... WHERE | PATCH | /tickets?id=eq.1, con los cambios en JSON |
| DELETE ... WHERE | DELETE | /tickets?id=eq.3 |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
POST, PATCH y DELETE cambian datos
Para añadir una fila, envías con POST su JSON. Para cambiar filas, envías con PATCH los cambios. Para quitarlas, envías DELETE.
Igual que en SQL, el filtro de la dirección decide qué filas se tocan. Un PATCH o un DELETE sin filtro tocaría todas las filas.
El servidor dice cómo fue con un código de estado.
Añadir un aviso y verlo volver
curl -s -w "\n" -X POST -H "Content-Type: application/json" -H "Prefer: return=representation" -d '{"title":"Monitor parpadea","priority":2}' "http://api:3000/tickets"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Cerrar el aviso 1
curl -s -o /dev/null -w "%{http_code}\n" -X PATCH -H "Content-Type: application/json" -d '{"status":"closed"}' "http://api:3000/tickets?id=eq.1"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Borrar el aviso 3
curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "http://api:3000/tickets?id=eq.3"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Una fila que la base rechaza
curl -s -w "\n%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"priority":1}' "http://api:3000/tickets"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Un error frecuente
Advertencia
Mucha gente cree que un código 2xx significa que la petición hizo lo que quería. El código solo dice que el servidor la entendió y la aceptó. Un PATCH cuyo filtro no coincide con nada responde igualmente 204. Vuelve a leer la tabla para comprobarlo.
Cerrar el aviso 99, que no existe
curl -s -o /dev/null -w "%{http_code}\n" -X PATCH -H "Content-Type: application/json" -d '{"status":"closed"}' "http://api:3000/tickets?id=eq.99"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Volver a leer la tabla
curl -s -w "\n" "http://api:3000/tickets?order=id"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Ejemplo resuelto: leer códigos de estado
| Código | Significado | Dónde aparece en la lección |
|---|---|---|
| 200 | Aquí están las filas | Al leer la tabla |
| 201 | Se creó una fila nueva | Un POST que no pide la fila de vuelta |
| 204 | Hecho, sin nada que devolver | El PATCH y el DELETE |
| 400 | La petición era errónea o rompía una regla | El aviso sin título |
| 404 | No existe esa tabla o dirección | Al pedir /nothing |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Pedir una tabla que no existe
curl -s -w "\n%{http_code}\n" "http://api:3000/nothing"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.