Una API REST da dirección a cada cosa
Una API REST es una API web en la que cada cosa que maneja, como un libro o un préstamo, tiene su propia dirección. El método de la petición dice qué hacer con ella.
Si diseñas bien las direcciones, quien use tu API adivina las que no ha visto. Si las diseñas mal, tiene que leer un manual para cada una.
Al terminar esta lección
Nota
Puedo elegir la ruta y el método de cada operación de una API.
Palabras clave
| Palabra | Qué significa | Ejemplo |
|---|---|---|
| Recurso | una cosa que la API maneja | un libro |
| Colección | todos los recursos de un mismo tipo | /books |
| Ruta | la parte de la dirección que nombra el recurso | |
| Método | la acción: leer, crear, cambiar o borrar | DELETE |
| Idempotente | que repetirlo deja el mismo resultado que hacerlo una vez |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
La ruta nombra una cosa, no una acción
En una buena API la ruta es un nombre en plural: /books, /loans. El verbo no va en la ruta, porque ya lo dice el método.
GET /books lista los libros. /getBooks mezcla el verbo y el nombre, y obliga a inventar otra ruta para cada acción.
Ejemplo resuelto: rutas con verbo y sin él
| Qué quieres | Ruta con verbo | Método y ruta |
|---|---|---|
| Listar los libros | GET /getBooks | GET /books |
| Ver el libro 7 | GET /showBook?id=7 | GET /books/7 |
| Añadir un libro | POST /addBook | POST /books |
| Borrar el libro 7 | POST /deleteBook?id=7 | DELETE /books/7 |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
Aquí un libro se pide con un filtro
Muchas APIs ponen el id en la ruta: /books/7. La API de este laboratorio usa un filtro: /books?id=eq.7. La idea es la misma.
La ruta nombra la colección, y lo que va tras el ? elige las filas. Para tu diseño en papel, usa /books/7. En el terminal, usa el filtro.
Un error frecuente
Advertencia
Mucha gente cree que la ruta debe llevar el verbo, como /deleteBook. El verbo ya está en el método. Úsalo solo para decir qué hacer. La ruta nombra la cosa, y un DELETE a /books ya dice borrar libros.
Cada método tiene un trabajo
GET lee y no cambia nada. POST crea un recurso nuevo. PUT lo reemplaza entero. PATCH cambia solo algunos campos. DELETE lo quita.
Una operación es idempotente si repetirla deja el mismo estado. GET, PUT y DELETE lo son. POST no: dos POST crean dos libros.
Ejemplo resuelto: los métodos, uno por uno
| Método | Trabajo | ¿Idempotente? |
|---|---|---|
| GET | Leer | Sí |
| POST | Crear | No |
| PUT | Reemplazar entero | Sí |
| PATCH | Cambiar una parte | Depende |
| DELETE | Quitar | Sí |
Las celdas que rellenan los estudiantes quedan en blanco en esta vista previa.
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.
Crear la tabla de libros
psql -h db -U shop -q -c "drop table if exists books; create table books (id serial primary key, title text not null, copies int not null default 1, status text not null default 'disponible'); insert into books (title, copies, status) values ('Redes de computadores', 3, 'disponible'), ('Algoritmos y estructuras', 0, 'prestado'), ('Sistemas operativos', 2, 'disponible'), ('Ingenieria del software', 1, 'disponible'); 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.
Crear un libro con POST
curl -s -o /dev/null -w "%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"title":"Redes seguras","copies":1}' "http://api:3000/books"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Cambiar dos campos del libro 2
curl -s -o /dev/null -w "%{http_code}\n" -X PATCH -H "Content-Type: application/json" -d '{"copies":4,"status":"disponible"}' "http://api:3000/books?id=eq.2"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Leer el libro 2 otra vez
curl -s -w "\n" "http://api:3000/books?id=eq.2"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 libro 4 con DELETE
curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "http://api:3000/books?id=eq.4"Se muestra aquí y no se ejecuta. Crea una cuenta gratuita para pulsar Ejecutar y escribirlo en el terminal de tu propio laboratorio.
Repetir un DELETE no cambia el resultado
Pulsa otra vez el Run de borrar el libro 4. Imprime 204 de nuevo, aunque el libro ya no existe. Esa es la idempotencia: el estado final es el mismo.
Repetir un POST sí cambiaría el estado, porque crearía otro libro.