Referencia API

Referencia completa de todas las clases, metodos y propiedades publicas de FoxServer.

ApiController

Clase base que deben heredar todos los controladores. Proporciona acceso a utilidades JSON, generacion de JWT, logging y el ciclo de vida del endpoint.

Metodos de respuesta

Propiedad / Metodo	Tipo	Descripcion
`newObject(fields)`	Object	Crea un objeto VFP dinamico. fields es una lista de nombres separados por coma.
`ToJson(obj)`	String	Serializa un objeto VFP a cadena JSON.
`FromJson(json)`	Object	Deserializa una cadena JSON a objeto VFP.
`GenerateJWT(user)`	String	Genera un token JWT firmado para el usuario indicado.
`GetUserIdFromToken(req)`	String	Extrae el ID de usuario del token JWT de la peticion.
`LogInfo(msg)`	Void	Escribe un mensaje INFO en el log del servidor.
`LogError(msg)`	Void	Escribe un mensaje ERROR en el log del servidor.
`QueueWebhook(url, secret, evt)`	Void	Encola un evento webhook para entrega asincrona.
`GetServerMetrics()`	Object	Retorna el objeto de metricas del servidor (uptime, requests, memoria...).

Hooks del ciclo de vida

Propiedad / Metodo	Tipo	Descripcion
`BeforeEndpoint(req, res)`	Boolean	Se ejecuta antes de cada endpoint. Retornar .F. aborta la peticion.
`AfterEndpoint(req, res)`	Void	Se ejecuta despues de cada endpoint. Para limpieza de recursos.
`BeforeRequest(req, res)`	Boolean	Hook a nivel de proyecto. Antes de cualquier enrutamiento.
`AfterResponse(req, res)`	Void	Hook a nivel de proyecto. Despues de enviar la respuesta.

FoxServerRequest

Objeto que encapsula toda la informacion de la peticion HTTP entrante. Disponible como parametro req en todos los endpoints.

Propiedades

Propiedad / Metodo	Tipo	Descripcion
`method`	String	GET, POST, PUT, PATCH, DELETE, HEAD
`url`	Uri	URL completa de la peticion como objeto Uri
`path`	String	Ruta sin query string. Ej: /api/v1/products
`params`	Object	Parametros de URL. Ej: params.id desde ruta /{id}
`query`	Object	Parametros de query string. Ej: query.page desde ?page=2
`headers`	Dictionary	Cabeceras HTTP. Acceso case-insensitive. Ej: headers.Authorization
`body`	String	Body de la peticion como texto plano (raw)
`json`	Object	Body JSON parseado. Solo disponible si Content-Type: application/json
`contentType`	String	Valor del header Content-Type
`remoteIP`	String	Direccion IP del cliente
`scheme`	String	"http" o "https"

Metodos

* Get URL param with fallback
lcId = req.GetParam("id", "")

* Check if a header was sent
IF req.HasHeader("X-Api-Key")
    lcKey = req.headers["X-Api-Key"]
ENDIF

* Safe JSON access (check before reading nested)
IF !ISNULL(req.json) AND !ISNULL(req.json.address)
    lcCity = req.json.address.city
ENDIF

FoxServerResponse

Objeto para construir y enviar la respuesta HTTP. Disponible como parametro res en todos los endpoints. Todos los metodos son encadenables (retornan res).

Propiedad / Metodo	Descripcion
`status(code)`	Establece el codigo de estado HTTP (200, 201, 400, 401, 404, 500...)
`json(jsonStr)`	Envia body JSON. Establece Content-Type: application/json automaticamente.
`send(text)`	Envia texto plano o HTML como body.
`header(key, value)`	Agrega o sobreescribe un header de respuesta. Encadenable.
`location(url)`	Establece el header Location. Usar con status(301) o status(302) para redireccion.
`sendFile(path, disp)`	Envia un archivo. disp puede ser "inline" (mostrar en navegador) o "attachment" (forzar descarga).

Ejemplo

* Standard success response
res.status(200).json(THIS.ToJson(loResult))

* Created with location header
res.status(201)
   .header("Location", "/api/v1/users/" + lcNewId)
   .json(THIS.ToJson(loResult))

* Error response
res.status(400).json('{"error":"Name is required"}')

* File download
res.status(200)
   .header("Content-Disposition", 'attachment; filename="report.pdf"')
   .sendFile("C:\reports\report.pdf", "attachment")

Metodos detallados de ApiController

Gestion de objetos y JSON

Propiedad / Metodo	Descripcion
`NewObject(fields)`	Crea un objeto VFP con propiedades inicializadas a NULL. fields es una lista separada por comas: "status,data,message".
`NewObjectFromCursor(cursor, session)`	Crea un objeto VFP con la estructura de un cursor. Util para crear plantillas basadas en estructuras de tabla.
`ToJson(obj)`	Serializa un objeto VFP a cadena JSON via JSONFox.
`ParseJson(jsonStr)`	Deserializa una cadena JSON a objeto VFP via JSONFox.
`TableToJson(cursor, currentRow)`	Convierte un cursor a JSON. currentRow=.T. devuelve el registro actual como objeto; .F. devuelve todos los registros como array.
`TableToJsonObject(cursor, currentRow, session)`	Igual que TableToJson pero retorna una coleccion de objetos VFP en lugar de cadena JSON. Util para manipular datos antes de la serializacion final.
`MasterToJSON(master, detail, expr, attr)`	Genera JSON jerarquico maestro-detalle. expr es la condicion de join (ej: "master.id = detail.master_id"), attr es el nombre del array de detalle en el JSON.

* Ejemplo: maestro-detalle con MasterToJSON
SELECT id, fecha, cliente FROM pedidos INTO CURSOR curPedidos
SELECT id, pedido_id, producto, cantidad FROM lineas INTO CURSOR curLineas
lcJson = THIS.MasterToJSON("curPedidos", "curLineas", "curPedidos.id = curLineas.pedido_id", "lineas")
res.status(200).json(lcJson)

Utilidades de texto y formato

Propiedad / Metodo	Descripcion
`Format(template, p0..p10)`	Sustituye marcadores {0}, {1}, ... en la cadena template. Similar a String.Format de C#.
`EscapeCharsToJSON(text)`	Escapa caracteres especiales para uso seguro en JSON (acentos, barras, comillas).
`EscapeCharsToHTML(text)`	Escapa caracteres especiales para uso en HTML (&, <, >, acentos).
`Content(req, source)`	Serializa source (cursor, objeto o string) al formato que el cliente solicita via Accept header o ?format= (json, xml, csv).
`TableToXml(cursor, currentRow)`	Convierte un cursor a XML.
`TableToCsv(cursor, currentRow)`	Convierte un cursor a CSV.

Utilidades de fecha, codificacion e identificadores

Propiedad / Metodo	Tipo	Descripcion
`NewGuid()`	String	Genera un GUID sin llaves ni guiones. Usar para todas las PKs.
`DTOUNX(dt, useMsec)`	Number	Convierte un DateTime VFP a timestamp Unix. useMsec=.T. devuelve milisegundos.
`UNXTOD(timestamp)`	DateTime	Convierte un timestamp Unix (segundos o milisegundos) a DateTime VFP.
`Base64URLEncode(input)`	String	Codifica en Base64URL (usado en JWT y URLs seguras).
`Base64URLDecode(input)`	String	Decodifica desde Base64URL.

* Conversiones de fecha
lnTs = THIS.DTOUNX(DATETIME(), .F.)   && segundos
ldFecha = THIS.UNXTOD(1716825600)

* Identificadores
lcId = THIS.NewGuid()   && "a1b2c3d4e5f647g8h9i0j1k2l3m4n5o6"

* Formato de mensajes
lcMsg = THIS.Format("Usuario {0} accedio a {1} desde {2}", lcUser, lcUrl, lcIp)

Ciclo de vida y recursos

Propiedad / Metodo	Descripcion
`Initialize()`	Se ejecuta automaticamente al crear una instancia. Configura cPath, carga JSONFox y ApiService.
`LoadJsonFox()`	Carga JSONFox.app si aun no esta disponible. Llamado internamente por Initialize().
`GetGlobalResource(name)`	Obtiene un recurso global compartido (conexiones, configuraciones) a traves del ciclo de vida de la aplicacion.
`SetWorkingDirectory(path)`	Establece cPath y llama a Initialize(). Util para testing fuera del ciclo de FoxServer.
`CleanUp() / Release() / Dispose()`	Libera recursos al finalizar el ciclo de vida del controlador. Invocados automaticamente por FoxServer.

FoxServerRequest — Metodos detallados

Propiedad / Metodo	Descripcion
`GetHeader(key, default)`	Retorna el valor del header HTTP indicado. Si no existe retorna default.
`GetParam(key, default)`	Retorna un parametro de ruta URL (ej: {id}). Retorna default si no existe.
`GetQuery(key, default)`	Retorna un parametro de query string (?key=value). Retorna default si no existe.
`GetQueryParams()`	Retorna todos los parametros de query como FoxServerTupleDictionary.
`HasJsonBody()`	.T. si la peticion tiene body JSON valido y parseado. Verificar antes de acceder a req.json.*.
`GetRawBody()`	Retorna el body de la peticion sin parsear. Necesario para verificar firmas de webhooks.
`GetFormField(key, default)`	Retorna el valor de un campo de formulario multipart o urlencoded.
`HasFormField(key)`	.T. si el campo de formulario existe en la peticion.
`File(field)`	Retorna el objeto de un archivo subido via multipart. Expone FileName y SaveToFile(path).
`Files(field)`	Retorna una coleccion de archivos subidos bajo el mismo nombre de campo.

* Leer headers y params
lcToken = req.GetHeader("Authorization", "")
lcId    = req.GetParam("id", "")
lcPage  = req.GetQuery("page", "1")

* Verificar body antes de acceder
IF req.HasJsonBody()
    lcEmail = req.json.email
ELSE
    res.status(400).json('{"error":"JSON body required"}')
    RETURN
ENDIF

* Subir archivo
loFile = req.File("avatar")
IF !ISNULL(loFile)
    loFile.SaveToFile(THIS.cPath + "uploads\" + loFile.FileName)
ENDIF

* Webhook: raw body para HMAC
lcRaw = req.GetRawBody()
lcSig = req.GetHeader("X-Signature", "")

Colecciones

FoxServerTupleDictionary

Diccionario clave-valor usado para Headers, Params y Query. Acceso case-insensitive.

Propiedad / Metodo	Descripcion
`Count`	Numero de entradas.
`GetKey(n)`	Clave en la posicion n (base 1).
`GetValue(n)`	Valor en la posicion n.
`Contains(key)`	.T. si la clave existe.
`GetValueByKey(key)`	Valor por nombre de clave.

* Iterar todos los query params
loParams = req.GetQueryParams()
FOR lnI = 1 TO loParams.Count
    lcKey = loParams.GetKey(lnI)
    lcVal = loParams.GetValue(lnI)
    THIS.LogInfo(THIS.Format("Param {0}={1}", lcKey, lcVal))
ENDFOR

FoxServerTuple

Par clave-valor simple. Componente interno de FoxServerTupleDictionary.

Propiedad / Metodo	Descripcion
`Key`	Nombre de la clave.
`Value`	Valor asociado.

Siguiente: Preguntas frecuentes →