Alles, was sgcREST kann, aufgeschlüsselt nach dem REST-Server und seinen Begleitern, der OpenAPI-Server-Engine und der OpenAPI-Client-Familie. Jede Fähigkeit arbeitet in Delphi und C++ Builder identisch, und jede Lizenz enthält den vollständigen Quellcode. Für diesen Launch sind noch keine Komponenten-Unterseiten veröffentlicht, jeder Eintrag unten ist auf dieser Seite in sich abgeschlossen.
CORS, Stats, Tenancy & Users
Spec-first & code-first
Jede über OpenAPI beschriebene API konsumieren
Delphi 7 bis 13, C++ Builder
sgcREST ist in sich geschlossen. Es bringt die sgcWebSockets Core Runtime mit, es ist also kein Add-on, und es läuft auf der Standard-Indy-Bibliothek, die mit RAD Studio ausgeliefert wird.
Code-first OpenAPI braucht Delphi XE7 oder neuer. Das Erzeugen einer Spezifikation aus einer attributierten Delphi-Klasse stützt sich auf RTTI, die mit XE7 kam. Der REST-Server, seine Begleiter und die spec-first-OpenAPI-Engine laufen auf Delphi 7 bis 13.
Vier Komponenten auf der Palettenseite SGC REST, und drei reine Code-Klassen für den OpenAPI-Server und -Client, deklariert in den Units sgcHTTP_REST_Server* und sgcHTTP_OpenAPI_*.
| Komponente | Klasse | Auf der Palette? | Beschreibung |
|---|---|---|---|
| REST Server | TsgcHTTPRESTServer | Ja | REST-API-Server auf Basis von TsgcHTTPServer, mit CORS-Handling und anschließbaren Stats-/Tenancy-Begleitern. |
| REST Server Stats | TsgcHTTPServerStats | Ja | Anfragezähler, Latenz-Tracking, Prometheus-/metrics und JSON-/health. |
| REST Server Tenancy | TsgcHTTPServer_Tenancy | Ja | Mandantenauflösung nach Host, Pfad, Header oder JWT-Claim. |
| REST Server Users | TsgcHTTPServer_Users | Ja | Lokaler Kontospeicher: Benutzer hinzufügen, validieren, hashen, mit Rollen-Tags versehen und persistieren. |
| OpenAPI Server, Spec-First | TsgcOpenAPIServerHandler | Nein, reine Code-Klasse | Bedient eine API aus einem geladenen OpenAPI-3.0-/3.1-Dokument, mit Anfrage-Validierung. |
| OpenAPI Server, Code-First | TsgcOpenAPICodeFirstScanner | Nein, reine Code-Klasse | Erzeugt die OpenAPI-Spezifikation aus einer RTTI-attributierten Delphi-Klasse. Braucht Delphi XE7+. |
| OpenAPI Client | TsgcOpenAPI_Client | Nein, reine Code-Klasse | Generischer Laufzeit-Client für jeden über OpenAPI beschriebenen Endpunkt. |
TsgcHTTPRESTServer ist ein TsgcHTTPServer-Nachfahre, er startet also mit denselben Bindungen und derselben TLS-Handhabung wie jeder sgc-HTTP-Server, und legt die üblichen Extras einer REST-API obendrauf.
| Fähigkeit | API | Hinweise |
|---|---|---|
| CORS | CORSOptions (Enabled, AllowOrigins, AllowHeaders, AllowMethods) | Standardmäßig aus. Preflight-OPTIONS-Anfragen werden automatisch beantwortet, sobald aktiviert. |
| Stats-Begleiter | ServerStats: TsgcHTTPServerStats | Hänge eine Stats-Komponente an, und jede Anfrage wird gezählt und zeitlich erfasst, ohne Route-Handler anzufassen. |
| Tenancy-Begleiter | Tenancy: TsgcHTTPServer_Tenancy, Tenant | Hänge eine Tenancy-Komponente an, um den Mandanten des Aufrufers aufzulösen; Tenant liest das Ergebnis für die aktuelle Anfrage. |
| Anfragezähler | TotalRequests, Status1xx bis Status5xx | Auf TsgcHTTPServerStats. Gezählt pro Statusklasse, sobald Antworten gesendet werden. |
| Latenz | LatencyMinMs, LatencyAvgMs, LatencyMaxMs | Pro Anfrage auf TsgcHTTPServerStats erfasst, zurückgesetzt mit Reset. |
| Metrics-Endpunkt | GetMetricsText, IsMetricsRequest | Prometheus-Textformat 0.0.4, bedient unter /metrics. |
| Health-Endpunkt | GetHealthJSON, IsHealthRequest | JSON-Health-Payload unter /health, enthält UptimeSeconds und ActiveConnections. |
| Stats pro Endpunkt | GetEndpointStats, Endpoints | Ein Pfad-/Zähler-Paar pro Endpunkt, für einen Bericht oder eine Admin-Konsole. |
| Mandantenauflösung | Resolution, ResolveTenant | Auf TsgcHTTPServer_Tenancy. Löst nach Host-Suffix, Pfadsegment, Header oder JWT-Claim auf. |
| Mandantenquellen | HostSuffix, PathSegmentIndex, HeaderName, ClaimName, DefaultTenant | Die Quelle, die für den konfigurierten Resolution-Modus gelesen wird, und der Fallback, wenn sie nichts liefert. |
| Eigene Auflösung | OnResolveTenant | Überschreibe oder erweitere die eingebaute Auflösungslogik. |
| Benutzerkonten | AddUser, DeleteUser, FindUser, ValidateCredentials, SetPassword, EnableUser, UserExists | Auf TsgcHTTPServer_Users. Gesalzene, gehashte Zugangsdaten, nie im Klartext zurückgegeben. |
| Rollen | AddRole, RemoveRole, UserHasRole, GetUserRoles | Frei definierbare Rollen-Tags pro Konto, geprüft aus einem Route-Handler. |
| Aufzählung | Count, GetUserCount, GetUserByIndex, GetUsernames | Nur-lese-Ansichten für einen Bericht oder eine Admin-Konsole; Passwort-Hash und Salt sind nie enthalten. |
| Persistenz | LoadUsers, SaveUsers, SaveToFile, LoadFromFile, ExportUsers, ImportUsers | Storage.EncryptAtRest verschlüsselt den Speicher; OnLoadUsers/OnSaveUsers tauschen ein eigenes Backend ein. |
| Ereignisse | OnStats, OnResolveTenant, OnValidateCredentials, OnFindUser, OnException | Ein Ereignis pro Begleiter für die Fälle, die die eingebaute Logik nicht abdeckt. |
Beide Ansätze speisen dieselbe Routentabelle und denselben Request-Kontext; nur die Quelle des OpenAPI-Dokuments unterscheidet sich.
| Fähigkeit | API | Hinweise |
|---|---|---|
| Routentabelle | TsgcOpenAPIRouteTable (Add, Match) | Aus dem paths-Abschnitt einer Spezifikation gebaut; ordnet ein Verb und einen Pfad einer operationId zu. |
| Request-Kontext | TsgcOpenAPIServerContext (Request, Response, PathParams, QueryParams) | Eine Instanz pro passender Anfrage, freigegeben, wenn die Anfrage endet. |
| Typisierte Parameter | PathParamAsString, PathParamAsInteger, QueryParamAsString, QueryParamAsInteger, QueryParamAsBoolean | Liest und konvertiert einen Pfad- oder Query-Wert in einem Aufruf. |
| Body-Zugriff | BodyAsString, BodyAsJSON, HeaderValue | Parst den Anfrage-Body einmal und cached das Ergebnis. |
| Antworten | RespondJSON, RespondError | Schreibt einen JSON-Body mit Statuscode, oder eine strukturierte Fehler-Payload. |
| Request-Lebenszyklus | BeforeHandle, AfterHandle, HandleException | Auf TsgcOpenAPIServerHandler. Überschreiben, um Logging, Auth-Prüfungen oder eigenes Fehler-Mapping zu ergänzen. |
| Validierung | TsgcOpenAPIJSONValidator | Prüft Anfrage-Bodys, Query- und Pfad-Parameter gegen die JSON-Schemas, die die Spezifikation deklariert. |
| Spezifikationserzeugung | GenerateSpec, Title, Description, Version, BasePath | Auf TsgcOpenAPICodeFirstScanner. Erzeugt ein OpenAPI-3.0-Dokument aus der RTTI einer attributierten Klasse. |
| Vertragsattribute | sgcServiceContract, sgcRoute, sgcSummary, sgcDescription, sgcTag, sgcResponse | Klassen- und methodenweite Attribute, die die erzeugte Spezifikation füllen. |
| Verb-Attribute | sgcHttpGet, sgcHttpPost, sgcHttpPut, sgcHttpDelete, sgcHttpPatch, sgcHttpHead, sgcHttpOptions | Deklariert das HTTP-Verb, das eine attributierte Methode beantwortet. |
| Parameterbindung | sgcFromPath, sgcFromQuery, sgcFromHeader, sgcFromBody, sgcRequired | Deklariert, woher jeder Methodenparameter gelesen wird. |
| Dispatch | TsgcOpenAPICodeFirstDispatcher (RegisterController, DispatchOperation, IsRegistered) | Ruft die für eine operationId registrierte, attributierte Methode direkt auf, keine manuelle if-Kette. |
| Abhängigkeit | Delphi XE7 oder neuer | Code-first-Scanning und -Dispatch stützen sich auf System.Rtti, vor XE7 nicht verfügbar. Spec-first hat diese Anforderung nicht. |
Ein generischer Client für jeden über OpenAPI beschriebenen Endpunkt, mit Basic-Auth, Bearer-Token, generischem OAuth2 und generischem JWT eingebaut.
| Fähigkeit | API | Hinweise |
|---|---|---|
| Basisaufruf | HTTP_REQUEST | Auf TsgcOpenAPI_Client. Trägt ein TsgcOpenAPIRequest-/TsgcOpenAPIResponse-Paar zu jedem Endpunkt. |
| Basis-URL | SetBaseURL, GetBaseURL | Der Endpunkt, gegen den jeder relative Pfad in einer Anfrage aufgelöst wird. |
| Generische Authentifizierung | Authentication (Basic, Token, OAuth2, JWT) | Basic-Auth und Bearer-Token, plus generische OAuth2- und JWT-Flows. |
| Transport | TLSOptions, ProxyOptions, EncodeBodyAsUTF8 | Standard-TLS- und Proxy-Konfiguration, geteilt mit dem übrigen sgc-HTTP-Stack. |
| Fortschritt & Logging | OnUpload, OnDownload, Log, LogFileName | Verfolgt große Anfrage-/Antwort-Bodys und protokolliert optional jeden Aufruf in eine Datei. |
| Request-Hook | OnBeforeRequest | Prüfe oder ändere eine Anfrage, bevor sie gesendet wird. |
| TLS-Hooks | OnSSLVerifyPeer, OnSSLGetHandler, OnSSLAfterCreateHandler | Zertifikatsprüfung und Handler-Anpassung, geteilt mit dem übrigen sgc-HTTP-Stack. |
Öffentliche Standards auf der Leitung, und derselbe Quellcode über jeden unterstützten Compiler hinweg.
| Bereich | Detail |
|---|---|
| OpenAPI | OpenAPI 3.0 und 3.1, sowohl für das spec-first-Routing des Servers als auch für die JSON-Schemas, gegen die die Anfrage-Validierung prüft. |
| Client-Authentifizierung | HTTP-Basic-Authentifizierung und Bearer-Token, plus generisches OAuth2 und JWT. |
| Metrics | Prometheus-Textformat 0.0.4 unter /metrics. |
| Plattformen | Windows Win32, Windows Win64, Linux64, macOS, iOS und Android für alle sieben Klassen. |
| Abhängigkeit | Keine über die mitgelieferte sgcWebSockets Core Runtime hinaus. Kein zusätzliches Add-on für eine der sieben Klassen. |
| Compiler | Delphi und C++ Builder 7 bis 13. Code-first OpenAPI braucht Delphi XE7 oder neuer. |
| Editionen | Die REST-Server-Familie steckt außerdem ab der Professional-Edition in sgcWebSockets, der OpenAPI-Server ab Enterprise, und der OpenAPI-Client ab Standard. |
| Lizenzierung | Eigenständig. Die sgcWebSockets Core Runtime ist mitgeliefert und der vollständige Quellcode ist enthalten. |