01
Qué es y qué problema resuelve
Una API modela recursos y ofrece operaciones con semántica predecible. La URI identifica una reserva; el verbo comunica intención.
GET no debería cambiarla. Crear mediante POST necesita explicar entrada, ubicación del resultado y efectos posibles.
La forma de una tabla no debe dictar los campos públicos.
02
Ejemplo paso a paso
Punto de partida Intercambio ilustrativo. La petición no permite escoger grupo, permisos ni estado de aprobación; el identificador de la respuesta se genera en servidor.
Antes de ejecutar
Contrato o esquema de diseño para analizar; no es una aplicación ejecutable completa. La evidencia principal es la decisión y su justificación. Una comprobación automatizada requiere implementar el control en una solución preparada.
POST /api/v1/reservas
Content-Type: application/json
{"salaId":"sala-norte","inicio":"2026-10-20T12:00:00Z",
"fin":"2026-10-20T13:00:00Z"}
HTTP/1.1 201 Created
Location: /api/v1/reservas/identificador-generadoCómo funciona
- Lee el verbo y la URL para reconocer qué solicita el cliente.
- Compara la respuesta 201 con el recurso que acaba de crearse.
- Observa Location: permite consultar la nueva representación.
Resultado esperado: El consumidor conoce dónde consultar la reserva creada; el grupo se deriva de identidad validada.
03
Cuándo usarlo y qué debes evitar
Diseña éxito y rechazo como parte del mismo contrato: 201 con Location al crear, 400 para entrada inválida, 401 para identidad no válida y 409 para conflicto con estado actual. Idempotencia describe efectos al repetir una intención; no significa que cualquier POST pueda reintentarse sin una clave.
Establece además qué recursos se ocultan mediante 404.
Ampliación opcional · contexto y variantes del tema
Contrato HTTP y DTOs explícitos
Un contrato describe entradas, respuestas, errores y permisos. Para crear una reserva acepta sala e intervalo; obtiene el grupo del contexto autenticado. No aceptes un objeto completo Reserva con Cancelada, propietario o auditoría modificables desde el cliente. Usa DTOs de entrada y salida pequeños; el DTO es el límite de confianza del transporte.
POST /api/v1/reservas crea y responde 201 con Location; GET de una reserva devuelve 200 o 404 según la política de visibilidad. 400 expresa entrada mal formada, 401 ausencia de autenticación válida y 403 acceso no autorizado. 409 puede expresar conflicto con estado actual. Un 500 corresponde a un fallo inesperado. Elegir 404 para ocultar recursos ajenos es una política consistente que debes aplicar y probar, no un reemplazo de comprobar permisos.
La ruta v1 es una estrategia de versionado visible. Agregar un campo opcional puede ser compatible; renombrar salaId o cambiar unidades de duración puede romper clientes. Conserva contratos de ejemplo en OpenAPI, acuerda deprecaciones y verifica consumidores. Un DTO compartido entre versiones deja de ser conveniente si ambas necesitan evolucionar de manera diferente.
Punto de partida Estos mensajes usan tipos conocidos por el serializador. El grupo se resuelve después de autenticar; no es un campo que el cliente pueda elegir.
Antes de ejecutar
Tipos completos para el adaptador HTTP
public sealed record CrearReservaDto(
string SalaId,
DateTimeOffset Inicio,
DateTimeOffset Fin);
public sealed record ReservaCreadaDto(Guid Id);Resultado esperado: La entrada no permite asignar un grupo ajeno ni marcar la reserva como aprobada.
04 · Práctica guiada · opcional
Practica lo aprendido
Define contrato para consultar y cancelar, incluyendo ausencia y acceso ajeno.
- 01Prepara el ejemplo con las dependencias indicadas en «Antes de ejecutar».
- 02Define contrato para consultar y cancelar, incluyendo ausencia y acceso ajeno.
- 03Comprueba y registra el resultado: El consumidor conoce dónde consultar la reserva creada; el grupo se deriva de identidad validada.
Ver solución orientativa
GET consulta sin efectos; cancelación especifica idempotencia. Autenticación y permiso se verifican antes de tocar estado.
05
Comprueba lo aprendido
Responde antes de abrir la explicación. Esta comprobación es opcional y no guarda una puntuación.
01¿REST exige exponer cada tabla como recurso?
No. El contrato responde a necesidades del consumidor y al dominio.
02¿Cómo sabe el portal dónde consultar lo que acaba de crear?
La respuesta de creación incluye Location con la URI de la reserva. El cliente consulta esa URI con GET; no necesita deducir una ruta a partir de tablas internas.
Cómo demostrar el objetivo
Compara tu práctica con estos resultados. Si solo diseñaste una prueba, registra su resultado como esperado, no como observado.
- El contrato de creación devuelve 201 con una ubicación del recurso creado.
- Defines consulta y cancelación con sus resultados de ausencia y acceso denegado, sin efectos en GET.
Qué debes recordar
- GET consulta sin efectos de negocio.
- Una creación debe comunicar su resultado y cómo localizar el recurso.
Tu cuaderno · notas personales
Cuaderno local
Tus notas del contenido
Se guardan únicamente en este dispositivo. Puedes exportarlas cuando quieras.
Material de apoyo · descarga, glosario y referencias
Explicaciones, ejemplos y prácticas propios de Academia de Software. Los fragmentos de integración requieren las dependencias indicadas; el ZIP contiene el núcleo de consola. Las lecturas externas se consultan en su sitio original y conservan sus condiciones. Procedencia y condiciones de uso.