# Servicio REST JSON con modelo, controlador y vista En esta guía escribirá un servicio de productos sobre MySQL con el formato `{success, data}`: siempre **HTTP 200** y un cuerpo `{"success": true, "data": ...}` o `{"success": false, "message": "..."}`. El código queda separado en tres piezas: | Pieza | Archivo | Responsabilidad | |---|---|---| | Modelo | `_protected/productos/modelo.dk` | Consultas y reglas de negocio (validaciones, alta o cambio) | | Vista | `_protected/productos/vista.dk` | Armar la respuesta JSON en el formato de la API | | Controlador | `_protected/productos/controlador.dkl` | Leer la petición, conectar, llamar al modelo y a la vista, atender errores | Cuándo usar esto y cuándo [CRUD-L](/es/devkron/2.0/marcos/crudl/): CRUD-L da las cinco operaciones sin código, pero responde la entidad sola con códigos HTTP. Escriba un servicio propio cuando necesite el formato `{success, data}`, reglas de negocio a la medida o una API que no corresponde una a una con tablas. Requisitos: un sitio funcionando (por ejemplo, el de [Crear un sitio nuevo](/es/devkron/2.0/guias/sitio-nuevo-nginx.md), aquí `misitio.localhost`) y una conexión `principal@tienda` en `connections.xml` hacia MySQL ([Conexiones](/es/devkron/2.0/instalacion/conexiones.md)) con las tablas de sistema `tuser` y `sys_session` y un usuario `web` (el script está en la guía [CRUD con MySQL](/es/devkron/2.0/guias/crud-mysql.md#1-prepare-la-base-de-datos)). ## 1. La tabla ```sql create table producto ( sys_pk int auto_increment primary key, sys_guid varchar(32), sys_dtcreated datetime, sys_timestamp datetime, sys_recver int default 0, sys_deleted tinyint default 0, sys_lock int null, sku varchar(30) not null unique, descripcion varchar(150) not null, precio decimal(14,2) not null default 0, existencia decimal(14,4) not null default 0 ); insert into producto(sys_guid,sys_dtcreated,sys_timestamp,sku,descripcion,precio,existencia) values (replace(uuid(),'-',''),now(),now(),'CUA-100','Cuaderno profesional 100 hojas',45.5,120), (replace(uuid(),'-',''),now(),now(),'LAP-HB','Lápiz HB',6,800); ``` Los campos `sys_*` son los del patrón de diseño de Devkron: así `dbr.save` sabe si inserta o actualiza y controla la concurrencia ([Biblioteca dbr](/es/devkron/2.0/bibliotecas/motor/dbr/modelo.md)). ## 2. La ruta Publique el servicio en una URL limpia. En `_protected/routes.map`: ```text /api/v1/productos/ > /_protected/productos/controlador.dkl ``` Los programas quedan en la carpeta protegida, fuera del alcance directo de las URL si [restringe esa carpeta](/es/devkron/2.0/marcos/servidor-web/enrutamiento.md#la-carpeta-protegida). ## 3. El modelo `_protected/productos/modelo.dk`: ```dkl #include "dkli.dkh" #! module "Modelo de productos" { productos.lista::&db, texto { new p { @"texto": texto } return dbr.list(db, "select sku, descripcion, precio, existencia from producto where ifnull(sys_deleted,0)=0 and (@texto='' or sku=@texto or descripcion like concat('%',@texto,'%')) order by descripcion limit 200;", p) } productos.uno::&db, sku { new p { @"sku": sku } ref r = dbr.rec(db, "select sku, descripcion, precio, existencia from producto where sku=@sku and ifnull(sys_deleted,0)=0;", p) if isnull(r) { do rise_error(404, "No existe el producto " + sku) } return r } productos.validar::&datos { if trim(@@(datos,"$sku")) == "" { do rise_error(400, "Falta el SKU") } if trim(@@(datos,"$descripcion")) == "" { do rise_error(400, "Falta la descripción") } if @@(datos,"#precio") < 0 { do rise_error(400, "El precio no puede ser negativo") } } // Da de alta o actualiza por SKU y devuelve el producto guardado productos.guardar::&db, &datos { do productos.validar(datos) new p { @"sku": @@(datos,"$sku") } ref actual = dbr.rec(db, "select sys_pk, sys_recver from producto where sku=@sku;", p) new reg { @"sku": @@(datos,"$sku") @"descripcion": @@(datos,"$descripcion") @"precio": @@(datos,"#precio") } if not(isnull(actual)) { reg<"sys_pk">: @@(actual,"#sys_pk") reg<"sys_recver">: @@(actual,"#sys_recver") } do dbr.save(db, "producto", reg) return productos.uno(db, @@(datos,"$sku")) } } ``` Puntos clave: - Los valores viajan siempre como **parámetros enlazados** (`@sku`, `@texto`), nunca concatenados en el SQL. - Para actualizar, `dbr.save` necesita el `sys_pk` **y** el `sys_recver` vigente; sin `sys_recver` falla con `Save Error. No fue posible actualizar la entidad`. - Los errores de negocio se lanzan con `rise_error`; el controlador los convierte en `{success:false}`. - El modelo no sabe nada de HTTP: se puede usar también desde una tarea de consola. ## 4. La vista `_protected/productos/vista.dk`: ```dkl #include "dkli.dkh" #! module "Vista JSON con el formato success/data" { vista.json::&respuesta { @http_context<"response/headers/content-type">: "application/json;charset=utf-8" @http_context<"response/output">: "text" @http_context<"response/text">: to.json(respuesta) } vista.ok::&datos { new r { @"success": @true } r<"data*">: datos do vista.json(r) } vista.error::mensaje { new r { @"success": @false @"message": mensaje } do vista.json(r) } } ``` ## 5. El controlador `_protected/productos/controlador.dkl`: ```dkl #include "dkli.dkh" #! program "API de productos" { #include "functions.dkh" #include "serialize.dkh" #include "dbr.dkh" #include "modelo.dk" #include "vista.dk" do errordet(@false) // mensajes de error sin código ni número de línea ref db = @null ref db = dbr.login("principal@tienda", "web", "MiClave#2026") metodo = toupper(@@(@http_context,"$request/headers/REQUEST_METHOD")) sku = @@(@http_context,"$request/get/sku") switch metodo { case "GET" { if sku == "" { do vista.ok(productos.lista(db, @@(@http_context,"$request/get/texto"))) } else { do vista.ok(productos.uno(db, sku)) } break } case "POST" { ref datos = @null codeblock { ref datos = from.json(@@(@http_context,"$request/POST_STRING")) exception { do rise_error(400, "El cuerpo debe ser JSON") } } do vista.ok(productos.guardar(db, datos)) break } default { do rise_error(405, "Método no admitido: " + metodo) } } do dbr.close(db) exception { if not(isnull(db)) { do dbr.close(db) } do vista.error(last_error()) } } ``` - `do errordet(@false)` hace que `last_error()` devuelva solo el mensaje (`No existe el producto NOEXISTE`), sin el código ni la línea que activa el controlador del servidor. - El `exception` final atrapa **cualquier** error (de negocio, de base de datos, de JSON) y responde `{success:false}` con estado 200: el servidor nunca muestra su página de error 500. - El controlador cierra la conexión en los dos caminos. (En 2.0, además, las conexiones abiertas se cierran al terminar cada petición.) - El SKU llega por la cadena de consulta (`?sku=`) y no como segmento de la ruta, porque los valores de `routes.map` llegan en minúsculas. - Las credenciales van fijas solo para el ejemplo; en su sistema use la conexión del usuario (proveedor de identidad) o lea las credenciales de un `config.dk` en la carpeta protegida. ## 6. Pruébelo Respuestas reales con Devkron 2.0 detrás de nginx: ```bash curl "http://misitio.localhost/api/v1/productos/?sku=CUA-100" ``` ```json {"success":1,"data":{"sku":"CUA-100","descripcion":"Cuaderno profesional 100 hojas","precio":45.50,"existencia":120.0000}} ``` | Petición | Respuesta | |---|---| | `GET /api/v1/productos/` | `{"success":1,"data":[{...},{...}]}` | | `GET /api/v1/productos/?texto=lápiz` | `{"success":1,"data":[{"sku":"LAP-HB","descripcion":"Lápiz HB",...}]}` | | `GET /api/v1/productos/?sku=NOEXISTE` | `{"success":0,"message":"No existe el producto NOEXISTE"}` | | `POST` `{"sku":"GOM-01","descripcion":"Goma blanca","precio":8.5}` | `{"success":1,"data":{"sku":"GOM-01","descripcion":"Goma blanca","precio":8.50,"existencia":0.0000}}` | | El mismo `POST` otra vez, con otra descripción | Actualiza: `{"success":1,"data":{...}}` | | `POST` `{"sku":"X","descripcion":"","precio":1}` | `{"success":0,"message":"Falta la descripción"}` | | `POST` `{"sku":"X","descripcion":"Y","precio":-1}` | `{"success":0,"message":"El precio no puede ser negativo"}` | | `POST` con `no es json` | `{"success":0,"message":"El cuerpo debe ser JSON"}` | | `DELETE /api/v1/productos/?sku=X` | `{"success":0,"message":"Método no admitido: DELETE"}` (HTTP 200) | Todas responden HTTP 200. `success` sale como `1` o `0` (así serializa `to.json` los valores lógicos); en JavaScript, `if (r.success)` funciona igual. ```bash curl -X POST "http://misitio.localhost/api/v1/productos/" \ -H "Content-Type: application/json;charset=utf-8" \ -d '{"sku":"GOM-01","descripcion":"Goma blanca","precio":8.5}' ``` ## Errores típicos | Síntoma | Causa y solución | |---|---| | `Save Error. No fue posible actualizar la entidad` al actualizar | Falta `sys_recver` (o no es el vigente) en el registro que se guarda | | La respuesta es la página 500 del servidor | Un error ocurrió fuera del bloque protegido, o falta el `exception` final | | Los mensajes traen `{404} ... [Ln= 14]` | Falta `do errordet(@false)` | | Acentos como `á` en los datos | Los datos se insertaron con otra codificación; cargue con `--default-character-set=utf8mb4` y use `utf8mb4` en la tabla | | `Función: productos.lista no reconocida` | El `#include` del modelo no encuentra el archivo: las rutas de `#include` son relativas a la carpeta del programa | ## Variantes - Con la biblioteca estándar [http.dkh](/es/devkron/2.0/bibliotecas/estandar/http.md), el controlador puede leer la petición con `httpreq.method()`, `httpreq.arg("sku")` y `httpreq.json()`. - Para operaciones que tocan varias tablas, vea [Transacciones bien hechas](/es/devkron/2.0/guias/transacciones.md). - Para exigir token, ponga la verificación en el `auth.dk` del sitio ([Autorización](/es/devkron/2.0/marcos/servidor-web/auth-y-render.md)).