少し前にGeneXusでプロシージャを作って、それをAPIとして呼んでみました。
イメージとしては下記のような感じです。
このプロシージャで作成したAPIは、HTTPメソッドを必ずPOSTで呼ぶことになります。
Getで呼ぶ場合はデータプロバイダーを作成する必要がありました。
またAPIが返却するステータスコードは自由に設定することもできませんでした。
しかしGeneXus17以降APIオブジェクトが登場し、APIオブジェクトを経由してプロシージャを呼ぶことができるようになりました。
またこちらもイメージとして表すと、下記のような感じです。
APIオブジェクトを経由することで、HTTPメソッドを自由に決められて、またステータスコードも好きなステータスコードを返すことが可能になったので、今回はそちらを記事にしようと思います。
APIオブジェクト作成
まずはAPIオブジェクトを作成します。
前回作成したプロシージャが商品データを取得するものだったので、今回は「ShohinAPI」としました。
まず前回のおさらいなのですが、プロシージャは「GetShohinP」と言う名前で、商品IDを受け取って、商品テーブルを見て対象の商品データを返しました。
パラメータで商品IDが空の場合は、全件返すようにしてます。
Rules
Source
今回はこちらのプロシージャをAPIオブジェクトから呼ぶようにします。
書き方は下記のような感じです。
まず1行目の「Shohin」と書いてある部分は何でも良いです。
2行目はHTTPメソッドを指定できます。
こちらは省略すると自動的にGetになります。
3行目に「GetShohin」と書いてありますが、こちらも1行目と同様何でも良いです。
そして4行目にプロシージャを記載してください。
「=>」を書かないといけないみたいです。
なんか新しい書き方ですね。
これでAPIオブジェクトからプロシージャをGetで呼べるようになりました。
YAMLファイルの確認
APIオブジェクトを作ってビルドすると、YAMLファイルと言うものができます。
今回出力されたYAMLファイルとは、簡単に言うとAPIの設計書みたいなものを既定のフォーマットで書き出したものだと思ってください。
JAVA環境だとwebフォルダ配下とTomcatのStaticフォルダの中にできます。
Static配下にあるのでブラウザでも開けるけど、エディタで開くと下記のような感じ。
APIのURLとかメソッド名とかパラメータとか書いてありますね。
ちなみにこれをPostmanにインポートすると簡単に呼ぶことができます。
APIオブジェクトの呼出し
今回も前回同様Postmanから呼んでみましょう。
まずYAMLファイルをインポートします。
下記の「インポート」を押下して出てきた画面にYAMLファイルをドラッグ＆ドロップします。
※インポートはPostmanのアカウントを作ってサインインしてないとできません。
そうすると下記のようなものが一発で出来上がります。
ちなみに{{baseUrl}}の部分は下記のようになってます。
あとはパラメータの値を変えて実行！
無事にプロシージャがGetで呼べて、値も正常に返ってきましたね。
次はステータスコードを返してみましょう。
ステータスコードの実装
今回はパラメータで商品IDを受け取ってますが、空だったらエラーコード「412」を返そうと思います。
また商品IDが空ではないが、商品テーブルに存在しないIDの場合はエラーコード「404」を返すようにします。
まず受け取った商品IDが空の場合のエラーコード実装は下記のとおりです。
記載するところはAPIオブジェクトのEventsタブです。
「Event メソッド名.Before」でプロシージャを呼ぶ前の処理を書くことができます。
次にプロシージャを呼んで戻ってきた値によってエラーを記述したい場合は下記のように記載します。
今度は「Event メソッド名.After」で記載します。
実装は以上です。
ステータスコードの検証
まずパラメータの商品IDを空でAPIを呼び出します。
想定通りステータスコード「412」が返ってきてますね。
次に商品テーブルに存在しないIDを渡してAPIを呼び出してみます。
こちらも想定通りステータスコード「404」で返ってきてメッセージも取れてます。
疑問
PostmanからAPIに渡した商品IDがあった場合は、Shohin_SDTのJson型が返ってきて、なかった場合はMessagesのJson型が返ってきてますね。
商品IDがあってもなくても、APIオブジェクトでoutしているSDTは2つなんだから、どんな場合でも２つ返ってくるのでは？
そんな質問をいただいたので検証してみると、どうやらSDTに何も入っていない場合はSDTのJson型が返ってこないみたいです。
試しに正常に商品が取れた場合、Shohin_SDTとMessagesを両方返すようにしてみました。
これで動かしてみると、下記のように２つのSDTがJson化されて返ってきました。
中身が空の場合は返ってこないというのが仕様みたいですね。
空の場合でも返したい場合は、戻りをLongVacharとかにして自分でSDTをJson化して戻してあげる必要があります。
まとめ
以上がGeneXusのAPIオブジェクトの説明になります。
今までAPIオブジェクトと言うものがあるのは知っていたのですが、プロシージャをAPI化すれば呼べたし、特に調べもしないで不要なものだと認識してました。
ただ今回APIオブジェクトについて質問いただいたので、ちょっと調べてみたら思った以上に色々できて、これは使えるなと思いました。
特にプロシージャを呼ぶ前にパラメータの確認や、実行結果によってステータスコードが変更できるのは良いですね。
今まではデータがなくてもAPIが正常に動けば「200」が返ってきていたのですが、「404」で返せるのはありがたいですね。
またAPIオブジェクトからYAMLファイルが作成されるので、SwaggerとかBlueprintに連携してAPI仕様書とか簡単に作れそうですね。
ちなみに今回はAPIオブジェクトに1つのプロシージャしか書きませんでしたけど、複数書くこともできます。
例えば商品を全件取得するAPIと、指定したデータのみ取得するAPIを2つに分けたい場合は、下記のように書けばプロシージャ1本で実現することが可能です。
メソッド名を変えて、プロシージャは同一でパラメータを変更します。
GetShohinPは商品IDが空の場合は全件取得して返すので、これで実現できます。
もしAPIを実装する機会がありましたら、ぜひAPIオブジェクトを作ってみてください。
