Endpoints de API JSON
No todos los endpoints necesitan devolver HTML. Las APIs JSON impulsan aplicaciones móviles, frontends de una sola página e integraciones de terceros. La única diferencia con un endpoint HTML es el tipo de contenido y el formato del cuerpo.
Devuelve JSON estableciendo el tipo de contenido a application/json:
GET "/api/status" :\n string body = "{\\"status\\": \\"ok\\", \\"version\\": \\"1.0\\"}"\n return http.respond(200, "application/json", body)\n\n GET "/api/users/:id" :\n string id = req.param("id")\n string params = "[\\"" + id + "\\"]"\n string result = db.query("SELECT username, email FROM users WHERE id = ? LIMIT 1", params)\n string username = json.get(result, "data.rows.0.username")\n if username == ""\n return http.respond(404, "application/json", "{\\"error\\": \\"Not found\\"}")\n string email = json.get(result, "data.rows.0.email")\n string body2 = "{\\"username\\": \\"" + username + "\\", \\"email\\": \\"" + email + "\\"}"\n return http.respond(200, "application/json", body2)GET /api/status → {"status": "ok", "version": "1.0"}\nGET /api/users/1 → {"username": "alice", "email": "alice@example.com"}\nGET /api/users/999 → 404 {"error": "Not found"}Establece el tipo de contenido a application/json para todas las respuestas de la API — tanto de éxito como de error. En Clean Language, los strings JSON se construyen con comillas escapadas dentro del literal de string. Devuelve objetos de error JSON consistentes para que los consumidores de la API puedan procesar los errores de la misma manera que los éxitos.
Un endpoint de verificación de estado es una buena primera API para agregar a cualquier servidor:
GET "/api/health" :\n string db_result = db.query("SELECT 1 as ok", "[]")\n string db_ok = json.get(db_result, "data.rows.0.ok")\n string status = "ok"\n if db_ok != "1"\n status = "degraded"\n string body = "{\\"status\\": \\"" + status + "\\"}"\n return http.respond(200, "application/json", body)GET /api/health → {"status": "ok"}SELECT 1 as ok es el ping de base de datos más simple posible. Si la base de datos es accesible, devuelve 1. Este patrón de verificación de estado permite que los balanceadores de carga y las herramientas de monitoreo verifiquen que tu servidor está activo sin tocar datos reales.
Resumen rápido
- Establece el tipo de contenido a application/json para los endpoints de la API
- Devuelve JSON tanto para respuestas de éxito como de error — nunca HTML desde una API
- Usa 404 con un cuerpo de error JSON para recursos no encontrados
- Un endpoint /api/health que hace ping a la BD es una buena primera cosa para agregar