Diseño de APIs
Requerimientos funcionales
● El primer paso en el diseño de una API es pensar TODO lo que la API
manejará.
● Típicamente, lo inicial será el Alta-Baja-Modificación de las entidades del
sistema.
Ej: Red Social
Entidad: Comentario
ABM: Operaciones para crear un comentario (¿en una publicación?), para
modificarlo y borrarlo.
○ El AMB incluye una 4ta operación para recuperar una entidad específica (CRUD).
Probablemente, también es importante recuperar todos los comentarios entre
fechas, recuperar los comentarios de un determinado usuario o de una
publicación.
Pensando en todas las entidades de una red social y sus respectivas acciones,
podemos listar las siguientes:
● Usuario: CRUD, comentarios, likes, publicaciones.
● Comentario: CRUD, lista, likes.
● Publicacion: CRUD, likes, comentarios, imagenes, videos, usuarios,
etiquetas, lista (fechas limites, etiqueta).
…
● A partir de que las acciones para cada entidad del sistema están definidas, se
pueden diseñar los endpoints para cada una de esas acciones.
● No es necesario que exista UN endpoint por cada acción (Ej: filtros).
● Para definir cada endpoint, tendremos que especificar su URL y, además, el
verbo que corresponde (GET, PUT, POST, DELETE).
Métodos GET
GET /comentarios: Este endpoint deberá devolver un listado de todos los
comentarios almacenados en el sistema.
GET /comentarios/<id>: Devolverá el comentario con identificador único <id>
GET /comentarios/<id1>,<id2>,<id3>: …
GET /publicaciones/<id>: …
Métodos GET. Subrecursos
En general, en cualquier sistema, existe una relación lógica entre la entidades del
sistema.
GET publicaciones/<id>/comentarios: Retorna una lista con los
comentarios de la publicación con id <id>.
GET publicaciones/<id>/etiquetas: …
GET usuarios/<id_usuario>/publicaciones/<id_pub>/imagenes:
Si cada publicación tiene un <id> independiente del usuario:
GET publicaciones/<id>/imagenes:
Método DELETE
Implementa la eliminación de los recursos:
Se puede implementar “soft” o “hard” delete
Soft: No se elimina del sistema, solamente se marca como eliminado. La
información queda en el sistema pero el usuario no la ve.
Hard: Se elimina directamente de la base de datos.
DELETE /usuarios/<id>: ...
DELETE /usuarios/<id>/publicaciones: Elimina todas las publicaciones
de un usuario.
Métodos PUT vs POST
La diferencia entre estos métodos no es siempre clara.
En general, se utiliza POST para crear un nuevo recurso en el sistema y PUT
para actualizar o modificar alguno ya existente.
POST /publicacion/<id>/comentario: Crear un nuevo comentario para la
publicación <id>.
PUT /publicacion/<id_p>/comentario<id_c>: Edita el comentario YA
EXISTENTE con id <id_c>.
Métodos PUT vs POST
En otros casos no es tan clara la diferencia y tenemos que ser más precisos en la
definición.
Ante la duda si debe ser un método PUT o POST, pensemos si la operación es
IDEMPOTENTE.
Una operación se dice IDEMPOTENTE cuando el resultado de aplicarla es el
mismo para 1 o múltiples veces. Ej: Multiplicar por 1 o por 0.
Ejercicio grupal
Defina los métodos utilizados para desarrollar una API para un sistema de venta de entradas
para eventos artísticos.
Defina al menos 3 entidades que el sistema deberá manejar.
Para las entidades definidas escriba un conjunto de acciones mínimo que el sistema deberá
implementar, no siempre tiene sentido TODAS las acciones para TODAS las entidades (Ej:
DELETE /usuarios ¿? )
Defina una estructura de datos para implementar el almacenamiento de datos por parte del
servidor. Piense las relaciones entre las entidades (Ej: Un usuario compra una entrada….)
Implemente al menos un CRUD completo para una entidad y métodos que involucren relaciones
entre entidades (Ej: Comprar una entrada por parte de un usuario)
