API-Referenz

Vollstandige Referenz aller offentlichen Klassen, Methoden und Eigenschaften von FoxServer.

ApiController

Basisklasse, von der alle Controller erben mussen. Bietet Zugang zu JSON-Dienstprogrammen, JWT-Generierung, Protokollierung und dem Endpunkt-Lebenszyklus.

Antwortmethoden

Eigenschaft / Methode	Typ	Beschreibung
`newObject(fields)`	Object	Erstellt ein dynamisches VFP-Objekt. fields ist eine kommagetrennte Namensliste.
`ToJson(obj)`	String	Serialisiert ein VFP-Objekt in einen JSON-String.
`FromJson(json)`	Object	Deserialisiert einen JSON-String in ein VFP-Objekt.
`GenerateJWT(user)`	String	Generiert einen signierten JWT-Token fur den angegebenen Benutzer.
`GetUserIdFromToken(req)`	String	Extrahiert die Benutzer-ID aus dem JWT-Token der Anfrage.
`LogInfo(msg)`	Void	Schreibt eine INFO-Nachricht in das Serverprotokoll.
`LogError(msg)`	Void	Schreibt eine ERROR-Nachricht in das Serverprotokoll.
`QueueWebhook(url, secret, evt)`	Void	Stellt ein Webhook-Ereignis fur asynchrone Zustellung in die Warteschlange.
`GetServerMetrics()`	Object	Gibt das Server-Metriken-Objekt zuruck (Uptime, Anfragen, Speicher...).

Lebenszyklus-Hooks

Eigenschaft / Methode	Typ	Beschreibung
`BeforeEndpoint(req, res)`	Boolean	Wird vor jedem Endpunkt ausgefuhrt. .F. zuruckgeben bricht die Anfrage ab.
`AfterEndpoint(req, res)`	Void	Wird nach jedem Endpunkt ausgefuhrt. Fur die Ressourcenbereinigung.
`BeforeRequest(req, res)`	Boolean	Hook auf Projektebene. Vor jeglichem Routing.
`AfterResponse(req, res)`	Void	Hook auf Projektebene. Nach dem Senden der Antwort.

FoxServerRequest

Objekt, das alle Informationen der eingehenden HTTP-Anfrage kapselt. Als Parameter req in allen Endpunkten verfugbar.

Eigenschaften

Eigenschaft / Methode	Typ	Beschreibung
`method`	String	GET, POST, PUT, PATCH, DELETE, HEAD
`url`	Uri	Vollstandige Anfrage-URL als Uri-Objekt
`path`	String	Pfad ohne Query-String. Z.B.: /api/v1/products
`params`	Object	URL-Parameter. Z.B.: params.id aus Route /{id}
`query`	Object	Query-String-Parameter. Z.B.: query.page aus ?page=2
`headers`	Dictionary	HTTP-Header. Zugriff ohne Beachtung der Gro-/Kleinschreibung. Z.B.: headers.Authorization
`body`	String	Anfrage-Body als Klartext (raw)
`json`	Object	Geparster JSON-Body. Nur verfugbar wenn Content-Type: application/json
`contentType`	String	Wert des Content-Type-Headers
`remoteIP`	String	IP-Adresse des Clients
`scheme`	String	"http" oder "https"

Methoden

* 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

Objekt zum Erstellen und Senden der HTTP-Antwort. Als Parameter res in allen Endpunkten verfugbar. Alle Methoden sind verkettbar (geben res zuruck).

Eigenschaft / Methode	Beschreibung
`status(code)`	Setzt den HTTP-Statuscode (200, 201, 400, 401, 404, 500...)
`json(jsonStr)`	Sendet JSON-Body. Setzt Content-Type: application/json automatisch.
`send(text)`	Sendet Klartext oder HTML als Body.
`header(key, value)`	Fugt einen Antwort-Header hinzu oder uberschreibt ihn. Verkettbar.
`location(url)`	Setzt den Location-Header. Mit status(301) oder status(302) fur Weiterleitung verwenden.
`sendFile(path, disp)`	Sendet eine Datei. disp kann "inline" (im Browser anzeigen) oder "attachment" (Download erzwingen) sein.

Beispiel

* 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")

ApiController — Detaillierte Methoden

Objekt- und JSON-Verwaltung

Eigenschaft / Methode	Beschreibung
`NewObject(fields)`	Erstellt ein VFP-Objekt mit auf NULL initialisierten Eigenschaften. fields ist eine kommagetrennte Liste: "status,data,message".
`NewObjectFromCursor(cursor, session)`	Erstellt ein VFP-Objekt mit der Struktur eines Cursors. Nutzlich fur Vorlagen auf Basis von Tabellenstrukturen.
`ToJson(obj)`	Serialisiert ein VFP-Objekt via JSONFox in einen JSON-String.
`ParseJson(jsonStr)`	Deserialisiert einen JSON-String in ein VFP-Objekt via JSONFox.
`TableToJson(cursor, currentRow)`	Konvertiert einen Cursor in JSON. currentRow=.T. gibt den aktuellen Datensatz als Objekt zuruck; .F. gibt alle als Array.
`TableToJsonObject(cursor, currentRow, session)`	Wie TableToJson, gibt aber eine VFP-Objektkollektion statt eines JSON-Strings zuruck.
`MasterToJSON(master, detail, expr, attr)`	Generiert hierarchisches Master-Detail-JSON. expr ist die Join-Bedingung, attr der Name des Detail-Arrays im 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)

Text- und Formatierungshilfsprogramme

Eigenschaft / Methode	Beschreibung
`Format(template, p0..p10)`	Ersetzt Platzhalter {0}, {1}, ... im Template. Ahnlich wie String.Format in C#.
`EscapeCharsToJSON(text)`	Maskiert Sonderzeichen fur die sichere Verwendung in JSON.
`EscapeCharsToHTML(text)`	Maskiert Sonderzeichen fur die Verwendung in HTML.
`Content(req, source)`	Serialisiert source in das Format, das der Client uber Accept-Header oder ?format= anfordert (json, xml, csv).
`TableToXml(cursor, currentRow)`	Konvertiert einen Cursor in XML.
`TableToCsv(cursor, currentRow)`	Konvertiert einen Cursor in CSV.

Datum-, Codierungs- und ID-Dienstprogramme

Eigenschaft / Methode	Typ	Beschreibung
`NewGuid()`	String	Generiert eine GUID ohne geschweifte Klammern oder Bindestriche. Fur alle PKs verwenden.
`DTOUNX(dt, useMsec)`	Number	Konvertiert einen VFP-DateTime in einen Unix-Zeitstempel. useMsec=.T. gibt Millisekunden zuruck.
`UNXTOD(timestamp)`	DateTime	Konvertiert einen Unix-Zeitstempel (Sekunden oder Millisekunden) in einen VFP-DateTime.
`Base64URLEncode(input)`	String	Codiert in Base64URL (wird in JWT und sicheren URLs verwendet).
`Base64URLDecode(input)`	String	Decodiert von 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)

Lebenszyklus und Ressourcen

Eigenschaft / Methode	Beschreibung
`Initialize()`	Wird beim Erstellen einer Instanz automatisch ausgefuhrt. Konfiguriert cPath, ladt JSONFox und ApiService.
`LoadJsonFox()`	Ladt JSONFox.app wenn noch nicht verfugbar. Wird intern von Initialize() aufgerufen.
`GetGlobalResource(name)`	Ruft eine gemeinsame globale Ressource (Verbindungen, Konfigurationen) uber den Anwendungslebenszyklus ab.
`SetWorkingDirectory(path)`	Setzt cPath und ruft Initialize() auf. Nutzlich fur Tests ausserhalb des FoxServer-Zyklus.
`CleanUp() / Release() / Dispose()`	Gibt Ressourcen am Ende des Controller-Lebenszyklus frei. Werden automatisch von FoxServer aufgerufen.

FoxServerRequest — Detaillierte Methoden

Eigenschaft / Methode	Beschreibung
`GetHeader(key, default)`	Gibt den Wert des angegebenen HTTP-Headers zuruck. Falls nicht vorhanden wird default zuruckgegeben.
`GetParam(key, default)`	Gibt einen URL-Routenparameter zuruck (z.B. {id}). Gibt default zuruck wenn nicht vorhanden.
`GetQuery(key, default)`	Gibt einen Query-String-Parameter zuruck (?key=value). Gibt default zuruck wenn nicht vorhanden.
`GetQueryParams()`	Gibt alle Query-Parameter als FoxServerTupleDictionary zuruck.
`HasJsonBody()`	.T. wenn die Anfrage einen gultig geparsten JSON-Body hat. Vor dem Zugriff auf req.json.* pruefen.
`GetRawBody()`	Gibt den ungeparsten Anfrage-Body zuruck. Notwendig fur die Webhook-Signaturverifizierung.
`GetFormField(key, default)`	Gibt den Wert eines Multipart- oder URL-kodierten Formularfeldes zuruck.
`HasFormField(key)`	.T. wenn das Formularfeld in der Anfrage vorhanden ist.
`File(field)`	Gibt das Objekt einer uber Multipart hochgeladenen Datei zuruck. Bietet FileName und SaveToFile(path).
`Files(field)`	Gibt eine Kollektion von Dateien zuruck, die unter demselben Feldnamen hochgeladen wurden.

* 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", "")

Kollektionen

FoxServerTupleDictionary

Schlussel-Wert-Worterbuch fur Headers, Params und Query. Zugriff ohne Beachtung der Gross-/Kleinschreibung.

Eigenschaft / Methode	Beschreibung
`Count`	Anzahl der Eintrage.
`GetKey(n)`	Schlussel an Position n (Basis 1).
`GetValue(n)`	Wert an Position n.
`Contains(key)`	.T. wenn der Schlussel vorhanden ist.
`GetValueByKey(key)`	Wert nach Schlusselnamen.

* 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

Einfaches Schlussel-Wert-Paar. Interne Komponente von FoxServerTupleDictionary.

Eigenschaft / Methode	Beschreibung
`Key`	Name des Schlussels.
`Value`	Zugeordneter Wert.

Weiter: FAQ →