データプロバイダーやプロシージャーなどの一連のプログラムのアプリケーション プログラミング インターフェースを定義します。
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,out:&Messages)
=> 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」部分を使用して実行できます。
- REST としてのみ公開される API では、サービスのオーバーロード (REST サービスでは一般的な、複数の異なる 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 ファイルで宣言されている大文字と小文字の区別に従って指定して、サービスの提供に使用されるジェネレーターに左右されないようにします。
- インターフェースの互換性または安定性の問題を回避するために、別のタイプのサービス (REST データプロバイダー、REST プロシージャー、REST ビジネスコンポーネントなど) の API オブジェクトで使用されているものと同じ構造化データタイプは使用しないことをお勧めします。これは、これらのサービスのシリアル化には差異がある可能性があるためです。
例
以下の例では、SDTClients という SDT が Core.ClientsList のみから呼び出されています:
Client{
List(out:&SDTClients)=> Core.ClientsList(&ClientCategoryCode,&SDTClients);
}
- また、API オブジェクトのインターフェースでコレクションとしてマークされた変数も使用しないことをお勧めします。これは、[ Json Collection Serialization ] プロパティを設定できないためです。コレクションを返す必要がある場合、コレクションとしてマークされた構造化データタイプの変数を使用するのではなく、構造化データタイプをコレクションとして定義する必要があります。
例
以下に示すコードでは、SDTClients という SDT がコレクションとして設定されていますが、API オブジェクト内で定義されている &SDTClients 変数はコレクションタイプではありません。
Client{
List(out:&SDTClients)=> Core.ClientsList(&ClientCategoryCode,&SDTClients);
}
この機能は、
GeneXus 17 の .NET および .NET Core、
GeneXus 17 Upgrade 2 の Java で使用できます。
GeneXus 17 Upgrade 1 では、標準の変数 &RestCode が追加されています。
API オブジェクトの構文
RestPath アノテーション
RestMethod アノテーション