sgcREST 機能一覧: REST サーバー & OpenAPI | eSeGeCe

sgcREST 機能一覧

sgcREST でできることすべてを、REST サーバーとそのコンパニオン、OpenAPI サーバーエンジン、OpenAPI クライアントに対応付けて示します。すべての機能は Delphi と C++ Builder で同じように動作し、すべてのライセンスに完全なソースコードが付属します。今回のローンチではコンポーネントのサブページはまだ公開されておらず、以下の各項目はこのページ内で完結しています。

REST サーバー

CORS、統計、テナンシー & ユーザー

OpenAPI サーバー

スペックファースト & コードファースト

OpenAPI クライアント

OpenAPI で記述された任意の API を利用

規格とプラットフォーム

Delphi 7 から 13、C++ Builder

sgcREST は単体で完結しています。sgcWebSockets Core ランタイムを同梱して出荷されるため、アドオンではなく、RAD Studio に同梱されている標準の Indy ライブラリの上で動作します。

コードファーストの OpenAPI には Delphi XE7 以降が必要です。属性を付けた Delphi クラスから仕様を生成する処理は、XE7 で導入された RTTI に依存しています。REST サーバーとそのコンパニオン、そしてスペックファーストの OpenAPI エンジンは Delphi 7 から 13 まで動作します。

コンポーネント

7 個のクラス、3 つのファミリー

SGC REST パレットページの 4 つのコンポーネントと、コードオンリーの OpenAPI サーバー・クライアントクラス 3 つ。sgcHTTP_REST_Server* ユニットと sgcHTTP_OpenAPI_* ユニットで宣言されています。

コンポーネントクラスパレット?説明
REST サーバーTsgcHTTPRESTServerありTsgcHTTPServer を土台にした REST API サーバーです。CORS 処理と、アタッチ可能な統計・テナンシーのコンパニオンを備えます。
REST サーバー統計TsgcHTTPServerStatsありリクエストのカウント、レイテンシー追跡、Prometheus 形式の /metrics、JSON 形式の /health。
REST サーバーテナンシーTsgcHTTPServer_Tenancyありホスト、パス、ヘッダー、JWT クレームによるマルチテナント解決。
REST サーバーユーザーTsgcHTTPServer_Usersありローカルアカウントストア。ユーザーの追加、検証、ハッシュ化、ロールタグ付け、永続化。
OpenAPI サーバー(スペックファースト)TsgcOpenAPIServerHandlerなし、コードオンリー読み込んだ OpenAPI 3.0/3.1 ドキュメントから API を提供し、リクエストを検証します。
OpenAPI サーバー(コードファースト)TsgcOpenAPICodeFirstScannerなし、コードオンリーRTTI 属性を付けた Delphi クラスから OpenAPI 仕様を生成します。Delphi XE7 以降が必要です。
OpenAPI クライアントTsgcOpenAPI_Clientなし、コードオンリーOpenAPI で記述された任意のエンドポイント向けの汎用ランタイムクライアントです。
REST Server

CORS、統計、テナンシー、ユーザーストア

TsgcHTTPRESTServer は TsgcHTTPServer のサブクラスなので、sgc HTTP サーバーが共通で持つバインディングと TLS 処理から出発し、その上に REST API に必要な定番の機能を重ねます。

機能API備考
CORSCORSOptions(Enabled、AllowOrigins、AllowHeaders、AllowMethods)既定は無効です。有効にすると、プリフライトの OPTIONS リクエストに自動で応答します。
統計コンパニオンServerStats: TsgcHTTPServerStats統計コンポーネントをアタッチすると、ルートハンドラーに手を加えることなくすべてのリクエストがカウントされ、時間計測されます。
テナンシーコンパニオンTenancy: TsgcHTTPServer_Tenancy、Tenantテナンシーコンポーネントをアタッチして呼び出し元のテナントを解決し、Tenant が現在のリクエストの結果を読み取ります。
リクエストカウンターTotalRequests、Status1xx から Status5xxTsgcHTTPServerStats 上。レスポンス送信時にステータスクラスごとにカウントされます。
レイテンシーLatencyMinMs、LatencyAvgMs、LatencyMaxMsTsgcHTTPServerStats 上でリクエストごとに追跡され、Reset でリセットできます。
メトリクスエンドポイントGetMetricsText、IsMetricsRequestPrometheus テキストエクスポジション形式 0.0.4 を /metrics で提供します。
ヘルスエンドポイントGetHealthJSON、IsHealthRequest/health で提供される JSON のヘルスペイロードで、UptimeSeconds と ActiveConnections を含みます。
エンドポイント別統計GetEndpointStats、Endpointsレポートや管理コンソール向けに、エンドポイントごとのパスとカウントのペアです。
テナント解決Resolution、ResolveTenantTsgcHTTPServer_Tenancy 上。ホストのサフィックス、パスセグメント、ヘッダー、JWT クレームで解決します。
テナントの取得元HostSuffix、PathSegmentIndex、HeaderName、ClaimName、DefaultTenant設定した Resolution モードが参照する取得元と、何も得られなかった場合のフォールバックです。
カスタム解決OnResolveTenant組み込みの解決ロジックを上書き、または拡張します。
ユーザーアカウントAddUser、DeleteUser、FindUser、ValidateCredentials、SetPassword、EnableUser、UserExistsTsgcHTTPServer_Users 上。ソルト付きでハッシュ化された認証情報は、平文で返されることはありません。
ロールAddRole、RemoveRole、UserHasRole、GetUserRolesアカウントごとの自由なロールタグで、ルートハンドラーから確認します。
列挙Count、GetUserCount、GetUserByIndex、GetUsernamesレポートや管理コンソール向けの読み取り専用ビューで、パスワードハッシュとソルトは含まれません。
永続化LoadUsers、SaveUsers、SaveToFile、LoadFromFile、ExportUsers、ImportUsersStorage.EncryptAtRest でストアを暗号化でき、OnLoadUsers/OnSaveUsers でカスタムバックエンドに差し替えられます。
イベントOnStats、OnResolveTenant、OnValidateCredentials、OnFindUser、OnException組み込みロジックがカバーしないケース向けに、コンパニオンごとに 1 つずつイベントが用意されています。
OpenAPI Server

スペックファーストのルーティング、コードファーストの生成

どちらのアプローチも同じルートテーブルとリクエストコンテキストに行き着き、異なるのは OpenAPI ドキュメントの出所だけです。

機能API備考
ルートテーブルTsgcOpenAPIRouteTable(Add、Match)仕様の paths セクションから構築され、動詞とパスを operationId に対応付けます。
リクエストコンテキストTsgcOpenAPIServerContext(Request、Response、PathParams、QueryParams)マッチしたリクエストごとに 1 インスタンスで、リクエスト終了時に解放されます。
型付きパラメータPathParamAsString、PathParamAsInteger、QueryParamAsString、QueryParamAsInteger、QueryParamAsBooleanパスまたはクエリの値を、1 回の呼び出しで読み取り、型変換します。
ボディアクセスBodyAsString、BodyAsJSON、HeaderValueリクエストボディを 1 度だけ解析し、結果をキャッシュします。
応答RespondJSON、RespondErrorステータスコード付きの JSON ボディ、または構造化されたエラーペイロードを書き込みます。
リクエストのライフサイクルBeforeHandle、AfterHandle、HandleExceptionTsgcOpenAPIServerHandler 上。オーバーライドしてログ記録、認証チェック、独自のエラーマッピングを追加できます。
検証TsgcOpenAPIJSONValidator仕様が宣言する JSON スキーマに対して、リクエストボディ、クエリ、パスパラメータを検証します。
仕様生成GenerateSpec、Title、Description、Version、BasePathTsgcOpenAPICodeFirstScanner 上。属性を付けたクラスの RTTI から OpenAPI 3.0 ドキュメントを生成します。
契約属性sgcServiceContract、sgcRoute、sgcSummary、sgcDescription、sgcTag、sgcResponse生成される仕様に反映される、クラスレベルおよびメソッドレベルの属性です。
動詞属性sgcHttpGet、sgcHttpPost、sgcHttpPut、sgcHttpDelete、sgcHttpPatch、sgcHttpHead、sgcHttpOptions属性を付けたメソッドが応答する HTTP 動詞を宣言します。
パラメータバインディングsgcFromPath、sgcFromQuery、sgcFromHeader、sgcFromBody、sgcRequired各メソッドパラメータの読み取り元を宣言します。
ディスパッチTsgcOpenAPICodeFirstDispatcher(RegisterController、DispatchOperation、IsRegistered)operationId に登録された属性付きメソッドを直接呼び出し、手動の if チェーンは不要です。
依存関係Delphi XE7 以降コードファーストのスキャンとディスパッチは System.Rtti に依存しており、XE7 より前では利用できません。スペックファーストにはこの要件はありません。
OpenAPI Client

1 つのランタイムクライアント、OpenAPI で記述された任意の API

OpenAPI で記述された任意のエンドポイント向けの汎用クライアントで、Basic 認証、ベアラートークン、汎用 OAuth2、汎用 JWT を内蔵しています。

機能API備考
基本呼び出しHTTP_REQUESTTsgcOpenAPI_Client 上。TsgcOpenAPIRequest/TsgcOpenAPIResponse のペアを任意のエンドポイントへ運びます。
ベース URLSetBaseURL、GetBaseURLリクエスト内のすべての相対パスが解決されるエンドポイントです。
汎用認証Authentication(Basic、Token、OAuth2、JWT)Basic 認証とベアラートークンに加えて、汎用の OAuth2 と JWT フローです。
トランスポートTLSOptions、ProxyOptions、EncodeBodyAsUTF8sgc HTTP スタックの他の部分と共通の、標準的な TLS とプロキシの設定です。
進捗 & ログOnUpload、OnDownload、Log、LogFileName大きなリクエスト/レスポンスボディを追跡し、任意ですべての呼び出しをファイルに記録できます。
リクエストフックOnBeforeRequest送信前にリクエストを検査、または変更します。
TLS フックOnSSLVerifyPeer、OnSSLGetHandler、OnSSLAfterCreateHandler証明書検証とハンドラーのカスタマイズで、sgc HTTP スタックの他の部分と共通です。
規格とプラットフォーム

API、コンパイラ、ターゲット

通信経路上の公開規格と、対応するすべてのコンパイラで共通のソースです。

項目内容
OpenAPIOpenAPI 3.0 と 3.1 に対応し、サーバーのスペックファーストルーティングと、リクエスト検証が照合する JSON スキーマの両方に使われます。
クライアント認証HTTP Basic 認証とベアラートークン、そして汎用の OAuth2 と JWT。
メトリクス/metrics での Prometheus テキストエクスポジション形式 0.0.4。
プラットフォーム7 個のクラスすべてで、Windows Win32、Windows Win64、Linux64、macOS、iOS、Android に対応します。
依存関係同梱の sgcWebSockets Core ランタイム以外はありません。7 個のクラスのいずれにも追加のアドオンは不要です。
コンパイラDelphi および C++ Builder 7 から 13 まで。コードファーストの OpenAPI には Delphi XE7 以降が必要です。
エディションREST サーバーファミリーは sgcWebSockets の Professional エディション以上に、OpenAPI サーバーは Enterprise エディション以上に、OpenAPI クライアントは Standard エディション以上にも含まれています。
ライセンス単体で完結します。sgcWebSockets Core ランタイムを同梱し、完全なソースコードが含まれます。
最もお得な選択: All-AccesseSeGeCe の全製品にプレミアムサポートが付いて、年間 €1,059 からご利用いただけます。
All-Access の価格を見る

sgcREST で開発する

無料体験版をダウンロードして、Delphi や C++ Builder から最初の REST エンドポイントや OpenAPI 呼び出しを組み立てましょう。

無料体験版をダウンロード 価格を見る