Construyendo una API RESTful

Imagina que estás creando una API para manejar una Pokédex. Tu API RESTful será: ordenada, eficiente. En este post, te mostraré cómo diseñar una API RESTful orientada a Pokémon, con ejemplos claros y buenas prácticas.

¿Qué es una API RESTful?

Una API RESTful sigue principios que la hacen ideal para construir sistemas como una Pokédex:

Recursos bien definidos
Cada Pokémon, movimiento o entrenador tiene su propia URL.

Verbos HTTP
GET para buscar Pokémon, POST para agregar nuevos, DELETE para liberar (eliminar) uno de tu equipo.

Stateless
Cada solicitud contiene toda la información necesaria, sin depender de un estado previo.

Ejemplo básico:

• GET /pokemons: Obtiene todos los Pokémon.
• GET /pokemons/\{id\}: Obtiene un Pokémon específico.
• POST /pokemons: Crea un nuevo Pokémon.
• DELETE /pokemons/\{id\}: Libera a un Pokémon (lo elimina).

Diseñando buenas rutas para la API

Para mantener tu API RESTful ordenada y descriptiva, define rutas claras y consistentes:

Malas rutas:

/api/getAllPokemons
/api/addPokemon
/api/deletePokemon?id=25

Buenas rutas:

/pokemons         -> GET para listar, POST para agregar.  
/pokemons/{id}    -> GET para detalles, PUT para actualizar, DELETE para liberar.  

Relaciones complejas

¿Qué pasa si quieres manejar ataques y movimientos de un Pokémon?

/pokemons/{id}/moves          -> Lista los movimientos de un Pokémon.  
/pokemons/{id}/moves/{moveId} -> Detalles de un movimiento específico.  

Verbos HTTP

Cada verbo HTTP tiene un propósito claro. Vamos a explicarlo con ejemplos de nuestra Pokédex:

• GET: Busca información.
  • GET /pokemons: Obtiene todos los Pokémon.
  • GET /pokemons/\{id\}: Obtiene los detalles de Pikachu.
• POST: Crea un nuevo recurso.
  • POST /pokemons: Añade a Bulbasaur a tu Pokédex.
• PUT: Actualiza un recurso completo.
  • PUT /pokemons/\{id\}: Cambia el nombre de tu Charizard.
• PATCH: Actualiza parcialmente un recurso.
  • PATCH /pokemons/\{id\}: Cambia solo el nivel de tu Gyarados.
• DELETE: Elimina un recurso.
  • DELETE /pokemons/\{id\}: Libera a Squirtle.

Códigos de respuesta

Tu API debe usar códigos HTTP que reflejen correctamente lo que ocurre con las solicitudes:

• 2xx (Éxito):
  • 200 OK: GET /pokemons/25 devuelve los datos de Pikachu.
  • 201 Created: POST /pokemons crea un nuevo Charmander.
  • 204 No Content: DELETE /pokemons/25 libera a Pikachu.
• 4xx (Errores del cliente):
  • 400 Bad Request: El cliente envió un ID inválido.
  • 404 Not Found: No existe un Pokémon con el ID proporcionado.
• 5xx (Errores del servidor):
  • 500 Internal Server Error: Algo salió mal al procesar la solicitud.

Yo prefiero evitar los errores 500, regularmente son errores no controlados en nuestro código, si son errores de validación de datos de entrada, podemos usar un código de retorno HTTP 400.

Buenas prácticas

Nombra los recursos en plural:
Usa /pokemons, no /pokemon.

Evita acciones en las rutas:
No uses rutas como /pokemons/add. En su lugar, usa POST /pokemons.

Documenta siempre tu API:
Incluye ejemplos claros en OpenAPI para que otros desarrolladores puedan usar tu Pokédex sin confusión.

Usa versionado:
Define versiones en tus rutas: /v1/pokemons. Esto facilita actualizaciones sin romper la API.

Valida las entradas:
Nunca confíes en que el cliente enviará datos correctos. Siempre usa validadores en tu código.

Ejemplo avanzado

Imagina que quieres implementar un sistema para que tus Pokémon peleen. Aquí tienes cómo estructurar las rutas:

/pokemons/{id}/battle             -> POST para iniciar una batalla.
/pokemons/{id}/battle/{opponentId} -> POST para pelear contra otro Pokémon.

Ejemplo de uso:
Un entrenador inicia una batalla contra otro Pokémon:

POST /pokemons/25/battle/133
Body: { "move": "Impactrueno" }
Response: 200 OK { "result": "¡Es súper efectivo! Eevee perdió 20 HP." }

Conclusión

Usando API RESTful puedes construir un sistema que sea tan organizado y eficiente para tus aplicaciones.

Ahora es tu turno: ¿Qué otros consejos puedes aportar al momento de crear servicios web RESTful? ¡Cuéntamelo en los comentarios! 🚀✨