カスタム処理と紐づいたAPIエンドポイントを作成する

Kurocoではカスタム処理と紐づいたエンドポイントの作成ができます。

カスタム処理を利用することのメリット

カスタム処理を利用することで、APIエンドポイントの標準機能だけでは実現が難しい処理を自由に追加できます。そのため、様々なユースケースに柔軟に対応できます。

例として、下記対応が可能です。

• リクエスト/レスポンス内容を変更する
• APIへの処理をフックする
• 独自のセキュリティ制御を実装する

このチュートリアルでは、カスタム処理とエンドポイントを紐付ける方法を紹介します。

GETエンドポイントとカスタム処理を作成する

まずはGETエンドポイントの例を紹介します。
ここでは例として、PlainCustomFunctionという名前のカスタム処理をAPIエンドポイントと紐付けます。

GETエンドポイントを作成する

カスタム処理と紐づけるためのエンドポイントを作成します。

エンドポイント一覧画面より、[新しいエンドポイントの追加]をクリックします。

今回は下記のように作成しました。

設定項目	設定
パス		plain-custom-endpoint
	有効/無効	有効
モデル	カテゴリー	API
	モデル	Api、v1
	オペレーション	request_api
サマリー(任意)		PlainCustomFunction 注：わかりやすい名前を記載してください。後に作成するカスタム処理名の記載を推奨します。
ディスクリプション(任意)		PlainCustomFunctionと紐づくGETエンドポイントです。 注：わかりやすい説明を記載してください。カスタム処理の意図/機能の記載を推奨します。
基本設定	name	PlainCustomFunction 注:後に作成するカスタム処理のslugを指定します。

GETエンドポイント用のカスタム処理を作成する

次に、作成したGETエンドポイント用のカスタム処理を作成します。

カスタム処理一覧画面より、[追加]をクリックします。

下記の設定で作成します。

項目	説明
タイトル	PlainCustomFunction
カテゴリ	未分類
識別子	PlainCustomFunction
処理	下記ソースコードの内容を記載してください。
ステータス	有効

{assign var="data" value=”Hello!"}

GETエンドポイントの動作確認をする

それでは、作成したエンドポイントの動作確認をします。 今回はSwaggerUI画面から確認します。

エンドポイント一覧画面より、[Swagger UI]をクリックします。

先ほど作成した、plain-custom-endpointをクリックします。

[Try it out]をクリックします。

[Execute]をクリックします。

すると、Response bodyにカスタム処理で作成した内容が表示されていることが確認できます。

以上で、GETエンドポイントとカスタム処理の紐付け完了です。

POSTエンドポイントとカスタム処理を作成する

次に、POSTエンドポイントの例を紹介します。 ここでは例として、PlainCustomFunctionPostという名前のカスタム処理を作成することとし、サマリー/ディスクリプションに説明例を記載しています。

POSTエンドポイントを作成する

カスタム処理と紐づけるためのエンドポイントを作成します。

エンドポイント一覧画面より、[新しいエンドポイントの追加]をクリックします。

今回は下記のように作成しました。

設定項目	設定
パス		plain-custom-endpoint-post
	有効/無効	有効
モデル	カテゴリー	API
	モデル	Api、v1
	オペレーション	request_api_post
サマリー(任意)		PlainCustomFunctionPost 注：わかりやすい名前を記載してください。後に作成するカスタム処理名の記載を推奨します。
ディスクリプション(任意)		PlainCustomFunctionPostと紐づくPOSTエンドポイントです。 注：わかりやすい説明を記載してください。カスタム処理の意図/機能の記載を推奨します。
基本設定	name	PlainCustomFunctionPost 注:後に作成するカスタム処理のslugを指定します。

POSTエンドポイント用のカスタム処理を作成する

次に、作成したPOSTエンドポイント用のカスタム処理を作成します。

カスタム処理一覧画面より、[追加]をクリックします。

下記の設定で作成します。

項目	説明
タイトル	PlainCustomFunctionPost
カテゴリ	未分類
識別子	PlainCustomFunctionPost
実行内容	下記ソースコードの内容を記載してください。
ステータス	有効

{assign var="message" value="Hello "|cat:$smarty.post.name}
{assign var="data" value=$message}

POSTエンドポイントの動作確認をする

それでは、作成したエンドポイントの動作確認をします。 今回はSwaggerUI画面から確認します。

エンドポイント一覧画面より、[Swagger UI]をクリックします。

先ほど作成した、plain-custom-endpoint-postをクリックします。

[Try it out]をクリックします。

Response body に以下のように入力します。

{
  "name": "Kuroco"
}

[Execute]をクリックします。

すると、Response bodyにカスタム処理で作成した内容が表示されていることが確認できます。

以上で、POSTエンドポイントとカスタム処理の紐付け完了です。

任意のリクエスト変数を付与する

上述の通り作成したエンドポイントは任意のリクエスト変数を受け付ける事ができます。
カスタム処理内でリクエスト変数を扱うには以下のように記述します。

• GET変数 : $smarty.get.hoge
• POST変数 : $smarty.post.foo
• Cookie変数 : $smarty.cookie.bar

また、上記の３つをまとめたリクエスト変数も利用可能です。

• リクエスト変数 : $smarty.request.piyo

{assign var="message" value="Hello "|cat:$smarty.request.name}
{assign var="data" value=$message}

正常終了メッセージ・エラーメッセージを返す

レスポンスにエラーメッセージ(errors) や正常終了メッセージ(messages) を送信したい場合は、カスタム処理にて以下のように記述します。

{assign var="message" value="Hello "|cat:$smarty.post.name}
{assign var="data" value=$message}
{if $smarty.post.name|strlen > 10}
    {append var="errors" value="name should be less than 10 characters."}
{else}
    {append var="messages" value="name is valid."}
{/if}

この例では、POST変数nameに10文字以上の文字列が指定された場合はエラー、それ以外は正常終了メッセージをレスポンスしています。

SwaggerUI画面のRequest bodyに以下のように記載し、[Execute]をクリックしてみましょう。

{
  "name": "Kuroco"
}

実行結果（正常終了メッセージ）：

正常終了メッセージがレスポンスされる事を確認できました。

次にSwaggerUI画面のRequest bodyに以下のように記載し、[Execute]をクリックしてみましょう。

{
  "name": "KurocoDiverta"
}

実行結果（エラー）：

エラーメッセージがレスポンスされる事を確認できました。

レスポンスのステータスコードを変更したい場合は以下を参照してください。 関連記事：エラー時にレスポンスコードを変更する場合

カスタム処理の実装例について

以上でカスタム処理とAPIエンドポイントの紐付け方法の紹介を終わります。 このチュートリアルではシンプルに紐付けの方法のみの説明にとどめましたが、カスタム処理の実装についてもっと詳しく知りたい場合は、下記ユースケース別のチュートリアルを参照してください。

• カスタム処理を利用して、APIエンドポイントに独自のスタブを設定する
• カスタム処理を利用して、APIに独自のバリデーションを実装する
• カスタム処理を利用して、APIのメイン処理に渡すリクエスト値を書き換える