データプロバイダーやプロシージャーなどの一連のプログラムのアプリケーション プログラミング インターフェースを定義します。
API オブジェクトは、意味的および機能的に関連する複数のサービスをグループ化します。各サービスについて、その外部名 (サービスとして公開) と
ナレッジベース (KB) 内部実装のマッピングを宣言します。サービスの宣言における柔軟性を特徴としており、サービスが REST の場合に HTTP メソッドの設定を使用できます。また、パラメーターの名前およびタイプも指定でき、パラメーター変換における柔軟性が大幅に増します。
API メディエーションレイヤーをモデル化するためのオブジェクトで、インターフェースと実装を明確に分離して、進化する API を段階的に開発および管理できるようにします。
API のインターフェースは、オブジェクトの「Service Source」部分で宣言されます。
インターフェースの各サービスについて、次の要素を宣言できます:
- 名前
- パラメーター
- どの GeneXus オブジェクトに実装が含まれており、どのパラメーターを使用してそれが呼び出されるか
- プロトコル固有のオプション用のアノテーション
API オブジェクトでは、次のプロトコル用の API を公開できます:
オブジェクトレベルで、それぞれを有効にするプロパティがあります。
(*) gRPC プロトコルは
.NET Framework ジェネレーターではサポートされていません。
.NET および
Java のジェネレーターでは、ベータの状態です。
イベントは、オブジェクトの [ Events ] エレメントで定義できます。
次のものを実行できます:
- サービスを実装するオブジェクトの呼び出しの前後における、サービスパラメーターのプログラムデータ変換。これは、安定した API を維持するのに役立ちます。
- トラフィックの管理、分析、およびサービスポリシーの適用。たとえば、サービスの呼び出しをカウントし、それらをログに記録し、API へのアクセスを許可または拒否します。
各 API オブジェクトに対して、各サービス実装の前後に実行される、「Before」イベントおよび「After」イベントを定義できます。
また、各サービスに対して、「<サービス名>.Before|After」イベントを定義できます。サービスを呼び出すたびに次の処理が実行されます:
- Before イベント
- <サービス>.Before イベント
- [ Service Source ] で参照される、サービスの実装に対応するオブジェクト
- <サービス>.After イベント
- After イベント
[ Events ] ではデータベースへのアクセスはできません。そのようなロジックは、呼び出されるプロシージャーまたはデータプロバイダーに配置する必要があります。
[ Service Source ] や [ Events ] で使用する変数を定義できます。
各 API オブジェクトにいくつかの標準の変数があります:
- &Pgmname: オブジェクトの名前を格納します。
- &Pgmdesc: オブジェクトの説明を格納します。
- &RestMethod: オブジェクトの呼び出しに使用する HTTP メソッドを格納します。REST 以外のプロトコルを使用してオブジェクトを呼び出す場合は空になります。
- &RestCode: 返される HTTP ステータスコードをカスタマイズするときに設定できます。
注: &RestCode 変数に指定できるのは次のカテゴリの値です: 2xx および 4xx。詳細については、
SAC #50865 を参照してください。
以下は、オブジェクトレベルで設定できるプロパティです:
次の例では、Client という名前の API を示します。クライアントの一覧を示すサービス、特定のクライアントの詳細を取得するサービス、およびクライアントを挿入するサービスがあります。
API オブジェクトの「Service Source」部分:
Client{
List(out:&SDTClients)
=> Core.ClientsList(&ClientCategoryCode,&SDTClients);
GetByKey(in:&ClientId,out:&Client)
=> Core.ClientGetbyKey(&ClientId,&Client);
[ RestMethod(POST) ]
Insert(in:&ClientId,in:&ClientName,in:&ClientAddress,out:&Messages)
=> Core.ClientInsert(&ClientId,&ClientName,&ClientAddress,&Messages);
}
注:
- REST プロトコルを使用してアクセスする場合、List および GetByKey には HTTP の「GET」メソッドを介して、Insert には [ RestMethod(POST) ] アノテーションで宣言される「POST」を介してアクセスします。
- サービスパラメーターは in または out として宣言する必要があります。
- パラメーターのマッピングおよびパラメーター値の変換は、下に示すように [ Events ] エレメントを使用して実行できます。
- サービスのオーバーロードは、RestMethod アノテーションおよび RestPath アノテーションを組み合わせることで、REST インターフェースで実現できます。
- REST プロトコルの場合、URI は次のようになります:
URLBase/ModuleName/ApiObjectName/Method
この例では次のようになります:
URLBase/Core/Client/List
[ Services base path ] プロパティを使用していない場合は、URL は次のように表示されます:
URLBase/ServicesBasePath/Method
[ Events ] エレメントは次のようになります:
Event Before
Statsregister(&pgmname)
EndEvent
Event List.Before
&ClientCategoryCode = 'Any'
EndEvent
Event Insert.Before
if &ClientId <= 0
&RestCode = 412
return
endif
EndEvent
Event GetByKey.After
if &Client.ClientId = 0
&Message.Type = MessageTypes.Error
&Message.Description = format("Client %1 was not found",&ClientId)
&Messages.Add(&Message)
&RestCode = 404
endif
EndEvent
注:
- 「List.Before」では、API の一部ではないが、呼び出されるオブジェクトが必要とする変数を初期化します。
- この例の Insert サービスに関連付けられたプロシージャー (および Insert.After イベント) は、&ClientId が 0 より大きい場合にのみ実行されます。
この例のソースは次の記事からダウンロードできます:
API Object Playground。
[ Generate OpenAPI interface ] プロパティが有効な場合、GeneXus では、各 API オブジェクト用に、OpenAPI の仕様に従った .yaml ファイルが生成されます。このファイル (名前は <API オブジェクトの修飾名>.yaml) には、その API で公開されるサービスに関連する情報がすべて含まれています。
クエリ文字列内のパラメーター (サービスの入力パラメーター) は、& で区切って指定されます。また、Java の場合は大文字と小文字が区別されます。そのため、API を使用する場合は、.yaml ファイルで宣言されている大文字と小文字の区別に従って指定して、サービスの提供に使用されるジェネレーターに左右されないようにします。
-
OpenAPI インポートツールを使用して API オブジェクトの YAML を別のナレッジベースにインポートする場合、コレクションとしてマークされた SDT に基づいて変数を定義することは避けてください。代わりに、変数を作成し、API オブジェクトのインターフェースでコレクションとしてマークしてください。このプロセスに従わないと、生成されたプロシージャーでデシリアライゼーション中にキャンセルが発生する可能性があります。これは、SDT の JSON 形式に問題があることを示します。
はじめての API オブジェクト
API オブジェクトの構文
RestPath アノテーション
RestMethod アノテーション