Tout ce que fait sgcREST, réparti sur le serveur REST et ses compléments, le moteur serveur OpenAPI et la famille du client OpenAPI. Chaque capacité fonctionne de la même façon en Delphi et en C++ Builder, et chaque licence est livrée avec le code source complet. Les sous-pages par composant ne sont pas encore publiées pour ce lancement, chaque entrée ci-dessous est autonome sur cette page.
CORS, stats, tenancy et utilisateurs
Spec-first et code-first
Consomme n'importe quelle API décrite en OpenAPI
Delphi 7 à 13, C++ Builder
sgcREST est autonome. Il est livré avec le runtime sgcWebSockets Core inclus, ce n'est donc pas un complément, et il tourne sur la bibliothèque Indy standard livrée avec RAD Studio.
OpenAPI code-first a besoin de Delphi XE7 ou ultérieur. Générer une spécification à partir d'une classe Delphi annotée s'appuie sur la RTTI introduite dans XE7. Le serveur REST, ses compléments et le moteur OpenAPI spec-first tournent de Delphi 7 à 13.
Quatre composants sur la page de palette SGC REST, et trois classes pur code serveur et client OpenAPI, déclarés dans les unités sgcHTTP_REST_Server* et sgcHTTP_OpenAPI_*.
| Composant | Classe | Palette ? | Description |
|---|---|---|---|
| Serveur REST | TsgcHTTPRESTServer | Oui | Serveur d'API REST bâti sur TsgcHTTPServer, avec gestion CORS et des compléments stats/tenancy attachables. |
| Stats du serveur REST | TsgcHTTPServerStats | Oui | Compteurs de requêtes, suivi de latence, /metrics Prometheus et /health JSON. |
| Tenancy du serveur REST | TsgcHTTPServer_Tenancy | Oui | Résolution multi-tenant par hôte, chemin, en-tête ou revendication JWT. |
| Utilisateurs du serveur REST | TsgcHTTPServer_Users | Oui | Magasin de comptes local : ajoute, valide, hache, étiquette par rôle et persiste les utilisateurs. |
| Serveur OpenAPI, spec-first | TsgcOpenAPIServerHandler | Non, pur code | Sert une API depuis un document OpenAPI 3.0/3.1 chargé, avec validation des requêtes. |
| Serveur OpenAPI, code-first | TsgcOpenAPICodeFirstScanner | Non, pur code | Génère la spécification OpenAPI à partir d'une classe Delphi annotée par RTTI. Nécessite Delphi XE7+. |
| Client OpenAPI | TsgcOpenAPI_Client | Non, pur code | Client runtime générique pour tout point de terminaison décrit en OpenAPI. |
TsgcHTTPRESTServer est un descendant de TsgcHTTPServer, il part donc des mêmes bindings et de la même gestion TLS que partage chaque serveur HTTP sgc, et superpose par-dessus les extras habituels d'une API REST.
| Capacité | API | Notes |
|---|---|---|
| CORS | CORSOptions (Enabled, AllowOrigins, AllowHeaders, AllowMethods) | Désactivé par défaut. Les requêtes préliminaires OPTIONS reçoivent une réponse automatique une fois activé. |
| Complément stats | ServerStats: TsgcHTTPServerStats | Attache un composant de stats et chaque requête est comptée et chronométrée sans toucher aux gestionnaires de route. |
| Complément tenancy | Tenancy: TsgcHTTPServer_Tenancy, Tenant | Attache un composant de tenancy pour résoudre le tenant de l'appelant ; Tenant lit le résultat pour la requête en cours. |
| Compteurs de requêtes | TotalRequests, Status1xx à Status5xx | Sur TsgcHTTPServerStats. Comptés par classe de statut à l'envoi des réponses. |
| Latence | LatencyMinMs, LatencyAvgMs, LatencyMaxMs | Suivie par requête sur TsgcHTTPServerStats, remise à zéro avec Reset. |
| Point de terminaison metrics | GetMetricsText, IsMetricsRequest | Format d'exposition texte Prometheus 0.0.4, servi sur /metrics. |
| Point de terminaison health | GetHealthJSON, IsHealthRequest | Charge utile JSON de santé servie sur /health, inclut UptimeSeconds et ActiveConnections. |
| Stats par point de terminaison | GetEndpointStats, Endpoints | Une paire chemin/compteur par point de terminaison, pour un rapport ou une console d'administration. |
| Résolution du tenant | Resolution, ResolveTenant | Sur TsgcHTTPServer_Tenancy. Résout par suffixe d'hôte, segment de chemin, en-tête ou revendication JWT. |
| Sources du tenant | HostSuffix, PathSegmentIndex, HeaderName, ClaimName, DefaultTenant | La source lue pour le mode Resolution configuré, et le repli quand elle ne donne rien. |
| Résolution personnalisée | OnResolveTenant | Surcharge ou étend la logique de résolution intégrée. |
| Comptes utilisateurs | AddUser, DeleteUser, FindUser, ValidateCredentials, SetPassword, EnableUser, UserExists | Sur TsgcHTTPServer_Users. Identifiants salés et hachés, jamais renvoyés en clair. |
| Rôles | AddRole, RemoveRole, UserHasRole, GetUserRoles | Étiquettes de rôle libres par compte, vérifiées depuis un gestionnaire de route. |
| Énumération | Count, GetUserCount, GetUserByIndex, GetUsernames | Vues en lecture seule pour un rapport ou une console d'administration ; le hachage et le sel de mot de passe ne sont jamais inclus. |
| Persistance | LoadUsers, SaveUsers, SaveToFile, LoadFromFile, ExportUsers, ImportUsers | Storage.EncryptAtRest chiffre le magasin ; OnLoadUsers/OnSaveUsers substituent un backend personnalisé. |
| Événements | OnStats, OnResolveTenant, OnValidateCredentials, OnFindUser, OnException | Un événement par complément pour les cas que la logique intégrée ne couvre pas. |
Les deux approches alimentent la même table de routage et le même contexte de requête ; seule la source du document OpenAPI diffère.
| Capacité | API | Notes |
|---|---|---|
| Table de routage | TsgcOpenAPIRouteTable (Add, Match) | Construite depuis la section paths d'une spécification ; fait correspondre un verbe et un chemin à un operationId. |
| Contexte de requête | TsgcOpenAPIServerContext (Request, Response, PathParams, QueryParams) | Une instance par requête appariée, libérée à la fin de la requête. |
| Paramètres typés | PathParamAsString, PathParamAsInteger, QueryParamAsString, QueryParamAsInteger, QueryParamAsBoolean | Lit et convertit une valeur de chemin ou de requête en un seul appel. |
| Accès au corps | BodyAsString, BodyAsJSON, HeaderValue | Analyse le corps de la requête une seule fois et met le résultat en cache. |
| Réponse | RespondJSON, RespondError | Écrit un corps JSON avec un code de statut, ou une charge utile d'erreur structurée. |
| Cycle de vie de la requête | BeforeHandle, AfterHandle, HandleException | Sur TsgcOpenAPIServerHandler. Surcharge pour ajouter journalisation, vérifications d'auth ou mappage d'erreur personnalisé. |
| Validation | TsgcOpenAPIJSONValidator | Vérifie les corps de requête, les paramètres de requête et de chemin par rapport aux schémas JSON que déclare la spécification. |
| Génération de spécification | GenerateSpec, Title, Description, Version, BasePath | Sur TsgcOpenAPICodeFirstScanner. Produit un document OpenAPI 3.0 à partir de la RTTI d'une classe annotée. |
| Attributs de contrat | sgcServiceContract, sgcRoute, sgcSummary, sgcDescription, sgcTag, sgcResponse | Attributs au niveau classe et méthode qui alimentent la spécification générée. |
| Attributs de verbe | sgcHttpGet, sgcHttpPost, sgcHttpPut, sgcHttpDelete, sgcHttpPatch, sgcHttpHead, sgcHttpOptions | Déclare le verbe HTTP auquel répond une méthode annotée. |
| Liaison de paramètres | sgcFromPath, sgcFromQuery, sgcFromHeader, sgcFromBody, sgcRequired | Déclare la source de lecture de chaque paramètre de méthode. |
| Dispatch | TsgcOpenAPICodeFirstDispatcher (RegisterController, DispatchOperation, IsRegistered) | Invoque directement la méthode annotée enregistrée pour un operationId, sans chaîne if manuelle. |
| Dépendance | Delphi XE7 ou ultérieur | Le scan et le dispatch code-first s'appuient sur System.Rtti, indisponible avant XE7. Le spec-first n'a pas cette exigence. |
Un client générique pour tout point de terminaison décrit en OpenAPI, avec authentification Basic, jetons Bearer, OAuth2 générique et JWT générique intégrés.
| Capacité | API | Notes |
|---|---|---|
| Appel de base | HTTP_REQUEST | Sur TsgcOpenAPI_Client. Porte une paire TsgcOpenAPIRequest/TsgcOpenAPIResponse vers n'importe quel point de terminaison. |
| URL de base | SetBaseURL, GetBaseURL | Le point de terminaison contre lequel se résout chaque chemin relatif d'une requête. |
| Authentification générique | Authentication (Basic, Token, OAuth2, JWT) | Authentification Basic et jetons Bearer, plus flux OAuth2 et JWT génériques. |
| Transport | TLSOptions, ProxyOptions, EncodeBodyAsUTF8 | Configuration TLS et proxy standard partagée avec le reste de la pile HTTP sgc. |
| Progression et journalisation | OnUpload, OnDownload, Log, LogFileName | Suit les corps de requête/réponse volumineux et journalise en option chaque appel dans un fichier. |
| Point d'accroche de requête | OnBeforeRequest | Inspecte ou modifie une requête avant son envoi. |
| Points d'accroche TLS | OnSSLVerifyPeer, OnSSLGetHandler, OnSSLAfterCreateHandler | Vérification de certificat et personnalisation du handler, partagées avec le reste de la pile HTTP sgc. |
Des standards publics sur le fil, et le même source sur chaque compilateur pris en charge.
| Domaine | Détail |
|---|---|
| OpenAPI | OpenAPI 3.0 et 3.1, à la fois pour le routage spec-first du serveur et pour les schémas JSON contre lesquels la validation des requêtes vérifie. |
| Authentification client | Authentification HTTP Basic et jetons Bearer, plus OAuth2 et JWT génériques. |
| Métriques | Format d'exposition texte Prometheus 0.0.4 sur /metrics. |
| Plateformes | Windows Win32, Windows Win64, Linux64, macOS, iOS et Android pour les sept classes. |
| Dépendance | Aucune au-delà du runtime sgcWebSockets Core inclus. Aucun complément supplémentaire pour l'une des sept classes. |
| Compilateurs | Delphi et C++ Builder 7 à 13. L'OpenAPI code-first nécessite Delphi XE7 ou ultérieur. |
| Éditions | La famille du serveur REST est aussi livrée dans sgcWebSockets à partir de Professional, le serveur OpenAPI à partir d'Enterprise, et le client OpenAPI à partir de Standard. |
| Licence | Autonome. Le runtime sgcWebSockets Core est inclus et le code source complet est fourni. |