Lo que debes recordar

El método

La secuencia crece otra vez. Estos son los pasos de la UD1 y la UD2 con los tres que añade el diseño:

1. ¿De qué cosa hablo? Un sustantivo, en plural si es colección. Nunca un verbo
2. ¿Qué le hago? Eso elige el método HTTP, y con él si es idempotente
3. ¿Qué datos necesito? Ruta si identifican, query si filtran, cuerpo si son contenido
4. ¿Qué acepto y qué publico? Dos listas distintas, dos clases distintas
5. ¿Qué tiene que cumplir lo que llega? Y qué digo cuando no lo cumple
6. ¿Cómo puede terminar esto? Cada final, su código de estado
7. ¿Cómo demuestro que sigue funcionando mañana?

El paso uno decide más que ningún otro: si eliges bien el sustantivo, los cinco métodos HTTP te dan la mitad de la API sin pensar. Si eliges un verbo, cada funcionalidad nueva te obligará a inventar una ruta.

La idea más importante

Tu API es una promesa, y las promesas se hacen a alguien que no está delante. Todo lo que obligue a preguntarte algo es un defecto de diseño, aunque funcione perfectamente.

De ahí sale la unidad entera. Por eso las rutas se nombran para que se puedan adivinar, por eso el modelo no se publica, por eso un 400 dice qué campo corregir, y por eso todos los errores tienen la misma forma: para que nadie tenga que escribirte.

Lo que cambia por dentro y lo que se promete fuera son dos cosas

Modelo, DTO y mapper existen por esa frase. El modelo cambia cuando cambia tu código; el contrato cambia cuando decides romper una promesa. Si son la misma clase, cualquier refactorización es una promesa rota sin querer.

Las decisiones que tienes que saber justificar

Al terminar deberías poder responder

1. ¿Por qué devolver JSON no convierte una API en REST?
2. ¿Qué tres restricciones de REST cumples solo por usar HTTP bien?
3. ¿Qué distingue el nivel 1 del nivel 2, y el 2 del 3?
4. ¿Por qué una URL no debe contener un verbo?
5. ¿Cuándo se usa ruta anidada y cuándo un filtro?
6. Enumera las tres estrategias para exponer algo que no es CRUD, en orden.
7. ¿Qué diferencia hay entre un recurso, un modelo y una representación?
8. Nombra un campo que entra y no sale, y otro que sale y no entra.
9. ¿Qué es el mass assignment y por qué un DTO de entrada lo previene?
10. ¿Por qué un DTO de modificación usa Boolean y no boolean?
11. ¿Qué fallo concreto produce tener la conversión repartida en dos sitios?
12. ¿Por qué el mapper conoce el modelo y el DTO no?
13. ¿Qué comprueba una prueba de ida y vuelta que no comprueba un código de estado?
14. ¿Por qué la validación del navegador no protege nada?
15. Las anotaciones de validación no hacen nada. ¿Qué compruebas primero?
16. Diferencia entre @NotNull, @NotEmpty y @NotBlank, con un valor que las separe.
17. ¿Por qué un validador propio debe dejar pasar el nulo?
18. ¿Por qué un enum es mejor que validar un texto?
19. ¿Qué reglas no puede comprobar Bean Validation, y por qué?
20. ¿Por qué el manejador genérico no devuelve el mensaje de la excepción?
21. ¿Cuándo se responde 409 en lugar de 400 o 404?
22. ¿Qué tipo de fallo no detecta ninguna prueba de un endpoint aislado?

Si además puedes coger un dominio nuevo y escribir su contrato de recursos, sus DTO, sus reglas y su formato de error antes de programar nada, tienes lo que esta unidad quería darte.

El vocabulario de la unidad

Comprobación final del producto

La siguiente unidad

Tres unidades, tres preguntas. Ya están las tres respondidas:

1. UD1 · que responda
2. UD2 · que responda correctamente
3. UD3 · que esté bien diseñada

Existe una cuarta que no se ha abordado todavía:

¿Y esto quién lo mantiene?

Porque el contrato de tu API está bien, y detrás de él hay un controlador que guarda los datos, genera identificadores, busca, filtra y decide reglas de negocio. Todo junto, en una clase, sin una sola prueba que compruebe la lógica sin arrancar un servidor.

Fíjate en la cuarta fila. Esa regla la encontraste tú en la sesión 13, viste por qué una anotación de validación no podía resolverla y la dejaste apuntada. Lleva dos sesiones esperando un sitio donde vivir, y en la unidad siguiente lo encontrará.

El trabajo de estas tres semanas demuestra aquí su utilidad: la UD4 no cambiará ninguna ruta, ni un DTO, ni un código de estado. Va a reorganizar lo que hay detrás sin tocar el contrato. Tu colección de pruebas, que ya cubre la API entera, será exactamente lo que demuestre que no has roto nada por el camino.

Ya deberías ser capaz de

• Distinguir una API HTTP cualquiera de una API orientada a recursos.
• Nombrar recursos y URLs sin meter verbos ni acciones en la ruta.
• Separar el modelo interno de lo que la API publica mediante DTO.
• Validar la entrada antes de que llegue a la lógica y explicar qué falla.
• Devolver errores con un formato único, predecible y útil para quien consume.