Wszystko, co robi sgcREST, rozpisane na serwer REST i jego komponenty towarzyszące, silnik serwera OpenAPI oraz rodzinę klienta OpenAPI. Każda funkcja działa tak samo w Delphi i C++ Builder, a każda licencja zawiera pełny kod źródłowy. Podstrony komponentów nie są jeszcze opublikowane przy tej premierze, każdy wpis poniżej jest samodzielny na tej stronie.
CORS, statystyki, wielodostępność i użytkownicy
Spec-first i code-first
Korzystaj z dowolnego API opisanego w OpenAPI
Delphi od 7 do 13, C++ Builder
sgcREST jest samowystarczalny. Jest dostarczany z dołączonym środowiskiem uruchomieniowym sgcWebSockets Core, więc nie jest dodatkiem, i działa na standardowej bibliotece Indy dostarczanej z RAD Studio.
OpenAPI code-first potrzebuje Delphi XE7 lub nowszego. Generowanie specyfikacji z oznaczonej atrybutami klasy Delphi opiera się na RTTI wprowadzonym w XE7. Serwer REST, jego komponenty towarzyszące oraz silnik OpenAPI spec-first działają na Delphi od 7 do 13.
Cztery komponenty na stronie palety SGC REST oraz trzy klasy serwera i klienta OpenAPI dostępne wyłącznie z kodu, zadeklarowane w modułach sgcHTTP_REST_Server* i sgcHTTP_OpenAPI_*.
| Komponent | Klasa | Paleta? | Opis |
|---|---|---|---|
| Serwer REST | TsgcHTTPRESTServer | Tak | Serwer API REST zbudowany na TsgcHTTPServer, z obsługą CORS oraz dołączanymi komponentami towarzyszącymi statystyk i wielodostępności. |
| Statystyki serwera REST | TsgcHTTPServerStats | Tak | Liczniki żądań, śledzenie opóźnień, Prometheus /metrics i JSON /health. |
| Wielodostępność serwera REST | TsgcHTTPServer_Tenancy | Tak | Rozpoznawanie wielodostępne na podstawie hosta, ścieżki, nagłówka lub oświadczenia JWT. |
| Użytkownicy serwera REST | TsgcHTTPServer_Users | Tak | Lokalny magazyn kont: dodawanie, walidacja, haszowanie, tagi ról i utrwalanie użytkowników. |
| Serwer OpenAPI, spec-first | TsgcOpenAPIServerHandler | Nie, tylko kod | Serwuje API na podstawie wczytanego dokumentu OpenAPI 3.0/3.1, z walidacją żądań. |
| Serwer OpenAPI, code-first | TsgcOpenAPICodeFirstScanner | Nie, tylko kod | Generuje specyfikację OpenAPI z klasy Delphi oznaczonej atrybutami RTTI. Wymaga Delphi XE7+. |
| Klient OpenAPI | TsgcOpenAPI_Client | Nie, tylko kod | Uniwersalny klient uruchomieniowy dla dowolnego punktu końcowego opisanego w OpenAPI. |
TsgcHTTPRESTServer jest potomkiem TsgcHTTPServer, więc wychodzi z tych samych powiązań i obsługi TLS, które dzieli każdy serwer sgc HTTP, i dokłada na to zwykłe dodatki API REST.
| Możliwość | API | Uwagi |
|---|---|---|
| CORS | CORSOptions (Enabled, AllowOrigins, AllowHeaders, AllowMethods) | Domyślnie wyłączone. Żądania wstępne OPTIONS są obsługiwane automatycznie po włączeniu. |
| Komponent statystyk | ServerStats: TsgcHTTPServerStats | Podłącz komponent statystyk, a każde żądanie jest liczone i mierzone w czasie bez dotykania procedur obsługi tras. |
| Komponent wielodostępności | Tenancy: TsgcHTTPServer_Tenancy, Tenant | Podłącz komponent wielodostępności, aby rozpoznać dzierżawcę wywołującego; Tenant odczytuje wynik dla bieżącego żądania. |
| Liczniki żądań | TotalRequests, Status1xx do Status5xx | Na TsgcHTTPServerStats. Liczone według klasy statusu w miarę wysyłania odpowiedzi. |
| Opóźnienie | LatencyMinMs, LatencyAvgMs, LatencyMaxMs | Śledzone dla każdego żądania na TsgcHTTPServerStats, resetowane przez Reset. |
| Punkt końcowy metryk | GetMetricsText, IsMetricsRequest | Format ekspozycji tekstowej Prometheus 0.0.4, serwowany pod /metrics. |
| Punkt końcowy kondycji | GetHealthJSON, IsHealthRequest | Ładunek JSON kondycji serwowany pod /health, obejmuje UptimeSeconds i ActiveConnections. |
| Statystyki per punkt końcowy | GetEndpointStats, Endpoints | Jedna para ścieżka/liczba na punkt końcowy, do raportu albo konsoli administracyjnej. |
| Rozpoznawanie dzierżawcy | Resolution, ResolveTenant | Na TsgcHTTPServer_Tenancy. Rozpoznaje na podstawie sufiksu hosta, segmentu ścieżki, nagłówka lub oświadczenia JWT. |
| Źródła dzierżawcy | HostSuffix, PathSegmentIndex, HeaderName, ClaimName, DefaultTenant | Źródło odczytywane dla skonfigurowanego trybu Resolution oraz wartość zastępcza, gdy nic nie zwróci. |
| Niestandardowe rozpoznawanie | OnResolveTenant | Nadpisz albo rozszerz wbudowaną logikę rozpoznawania. |
| Konta użytkowników | AddUser, DeleteUser, FindUser, ValidateCredentials, SetPassword, EnableUser, UserExists | Na TsgcHTTPServer_Users. Poświadczenia z solą i haszowaniem, nigdy nie zwracane w postaci jawnej. |
| Role | AddRole, RemoveRole, UserHasRole, GetUserRoles | Dowolne tagi ról dla każdego konta, sprawdzane z procedury obsługi trasy. |
| Wyliczanie | Count, GetUserCount, GetUserByIndex, GetUsernames | Widoki tylko do odczytu do raportu albo konsoli administracyjnej; hasz hasła i sól nigdy nie są w nich zawarte. |
| Utrwalanie | LoadUsers, SaveUsers, SaveToFile, LoadFromFile, ExportUsers, ImportUsers | Storage.EncryptAtRest szyfruje magazyn; OnLoadUsers/OnSaveUsers podmieniają na własny backend. |
| Zdarzenia | OnStats, OnResolveTenant, OnValidateCredentials, OnFindUser, OnException | Jedno zdarzenie na komponent towarzyszący, dla przypadków, których nie obejmuje wbudowana logika. |
Oba podejścia trafiają do tej samej tablicy tras i kontekstu żądania; różni się tylko źródło dokumentu OpenAPI.
| Możliwość | API | Uwagi |
|---|---|---|
| Tablica tras | TsgcOpenAPIRouteTable (Add, Match) | Budowana z sekcji paths specyfikacji; dopasowuje czasownik i ścieżkę do operationId. |
| Kontekst żądania | TsgcOpenAPIServerContext (Request, Response, PathParams, QueryParams) | Jedna instancja na dopasowane żądanie, zwalniana po zakończeniu żądania. |
| Typowane parametry | PathParamAsString, PathParamAsInteger, QueryParamAsString, QueryParamAsInteger, QueryParamAsBoolean | Odczytuje i konwertuje wartość ścieżki lub zapytania w jednym wywołaniu. |
| Dostęp do treści | BodyAsString, BodyAsJSON, HeaderValue | Parsuje treść żądania raz i buforuje wynik. |
| Odpowiadanie | RespondJSON, RespondError | Zapisuje treść JSON z kodem statusu albo ustrukturyzowany ładunek błędu. |
| Cykl życia żądania | BeforeHandle, AfterHandle, HandleException | Na TsgcOpenAPIServerHandler. Nadpisz, aby dodać logowanie, kontrolę uwierzytelniania albo własne mapowanie błędów. |
| Walidacja | TsgcOpenAPIJSONValidator | Sprawdza treści żądań, parametry zapytania i ścieżki względem schematów JSON zadeklarowanych w specyfikacji. |
| Generowanie specyfikacji | GenerateSpec, Title, Description, Version, BasePath | Na TsgcOpenAPICodeFirstScanner. Wytwarza dokument OpenAPI 3.0 z RTTI oznaczonej atrybutami klasy. |
| Atrybuty kontraktu | sgcServiceContract, sgcRoute, sgcSummary, sgcDescription, sgcTag, sgcResponse | Atrybuty na poziomie klasy i metody, które wypełniają wygenerowaną specyfikację. |
| Atrybuty czasownika | sgcHttpGet, sgcHttpPost, sgcHttpPut, sgcHttpDelete, sgcHttpPatch, sgcHttpHead, sgcHttpOptions | Deklaruje czasownik HTTP, na który odpowiada oznaczona atrybutem metoda. |
| Wiązanie parametrów | sgcFromPath, sgcFromQuery, sgcFromHeader, sgcFromBody, sgcRequired | Deklaruje, skąd odczytywany jest każdy parametr metody. |
| Rozdzielanie | TsgcOpenAPICodeFirstDispatcher (RegisterController, DispatchOperation, IsRegistered) | Wywołuje bezpośrednio oznaczoną atrybutem metodę zarejestrowaną dla operationId, bez ręcznego łańcucha if. |
| Zależność | Delphi XE7 lub nowszy | Skanowanie i rozdzielanie code-first opierają się na System.Rtti, niedostępnym przed XE7. Spec-first nie ma takiego wymagania. |
Uniwersalny klient dla dowolnego punktu końcowego opisanego w OpenAPI, z wbudowanym uwierzytelnianiem Basic, tokenami bearer, ogólnym OAuth2 i ogólnym JWT.
| Możliwość | API | Uwagi |
|---|---|---|
| Wywołanie bazowe | HTTP_REQUEST | Na TsgcOpenAPI_Client. Niesie parę TsgcOpenAPIRequest/TsgcOpenAPIResponse do dowolnego punktu końcowego. |
| Adres bazowy | SetBaseURL, GetBaseURL | Punkt końcowy, względem którego rozwiązywana jest każda względna ścieżka w żądaniu. |
| Uwierzytelnianie ogólne | Authentication (Basic, Token, OAuth2, JWT) | Uwierzytelnianie Basic i tokeny bearer, a także ogólne przepływy OAuth2 i JWT. |
| Transport | TLSOptions, ProxyOptions, EncodeBodyAsUTF8 | Standardowa konfiguracja TLS i proxy, wspólna z resztą stosu sgc HTTP. |
| Postęp i logowanie | OnUpload, OnDownload, Log, LogFileName | Śledź duże treści żądań/odpowiedzi i opcjonalnie loguj każde wywołanie do pliku. |
| Hak żądania | OnBeforeRequest | Sprawdź albo zmień żądanie przed wysłaniem. |
| Haki TLS | OnSSLVerifyPeer, OnSSLGetHandler, OnSSLAfterCreateHandler | Weryfikacja certyfikatu i dostosowanie handlera, wspólne z resztą stosu sgc HTTP. |
Oficjalne standardy na łączu i te same źródła we wszystkich obsługiwanych kompilatorach.
| Obszar | Szczegóły |
|---|---|
| OpenAPI | OpenAPI 3.0 i 3.1, zarówno dla trasowania spec-first serwera, jak i dla schematów JSON, względem których waliduje żądania. |
| Uwierzytelnianie klienta | Uwierzytelnianie HTTP Basic i tokeny bearer, a także ogólne OAuth2 i JWT. |
| Metryki | Format ekspozycji tekstowej Prometheus 0.0.4 pod /metrics. |
| Platformy | Windows Win32, Windows Win64, Linux64, macOS, iOS i Android dla wszystkich siedmiu klas. |
| Zależność | Żadna poza dołączonym środowiskiem uruchomieniowym sgcWebSockets Core. Żaden dodatkowy dodatek dla żadnej z siedmiu klas. |
| Kompilatory | Delphi i C++ Builder od 7 do 13. OpenAPI code-first wymaga Delphi XE7 lub nowszego. |
| Edycje | Rodzina serwera REST jest dostarczana także wewnątrz sgcWebSockets od edycji Professional wzwyż, serwer OpenAPI od edycji Enterprise wzwyż, a klient OpenAPI od edycji Standard wzwyż. |
| Licencjonowanie | Produkt samodzielny. Środowisko uruchomieniowe sgcWebSockets Core jest dołączone, a pełny kod źródłowy jest w zestawie. |