カスタム処理と紐づいたAPIエンドポイントを作成する
Kurocoではカスタム処理と紐づいたエンドポイントの作成ができます。
カスタム処理を利用することのメリット
カスタム処理を利用することで、APIエンドポイントの標準機能だけでは実現が難しい処理を自由に追加できます。そのため、様々なユースケースに柔軟に対応できます。
例として、下記対応が可能です。
- リクエスト/レスポンス内容を変更する
- APIへの処理をフックする
- 独自のセキュリティ制御を実装する
このチュートリアルでは、カスタム処理とエンドポイントを紐付ける方法を紹介します。
GETエンドポイントとカスタム処理を作成する
まずはGETエンドポイントの例を紹介します。
ここでは例として、PlainCustomFunctionという名前のカスタム処理をAPIエンドポイントと紐付けます。
GETエンドポイントを作成する
カスタム処理と紐づけるためのエンドポイントを作成します。
エンドポイント一覧画面より、[新しいエンドポイントの追加]をクリックします。
今回は下記のように作成しました。
| 設定項目 | 設定 | |
|---|---|---|
| パス | plain-custom-endpoint | |
| 有効/無効 | 有効 | |
| モデル | カテゴリー | API |
| モデル | Api、v1 | |
| オペレーション | request_api | |
| サマリー(任意) | PlainCustomFunction 注：わかりやすい名前を記載してください。後に作成するカスタム処理名の記載を推奨します。 | |
| ディスクリプション(任意) | PlainCustomFunctionと紐づくGETエンドポイントです。 注：わかりやすい説明を記載してください。カスタム処理の意図/機能の記載を推奨します。 | |
| 基本設定 | name | PlainCustomFunction 注:後に作成するカスタム処理のslugを指定します。 |
use_path_paramのパラメータを有効にすると、/rcms-api/1/external_api/{data_id}のようにパスパラメータを受け付けます。
詳しい使い方は以下のドキュメントを参照してください。
GETエンドポイント用のカスタム処理を作成する
次に、作成したGETエンドポイント用のカスタム処理を作成します。
カスタム処理一覧画面より、[追加]をクリックします。
下記の設定で作成します。
| 項目 | 説明 |
|---|---|
| タイトル | PlainCustomFunction |
| カテゴリ | 未分類 |
| 識別子 | PlainCustomFunction |
| 処理 | 下記ソースコードの内容を記載してください。 |
| ステータス | 有効 |
{assign var="data" value=”Hello!"}
request_api に使用できる変数
| 変数名 | 型 | 説明 |
|---|---|---|
$data | object | この変数に代入した値は、dataの項目でレスポンスされます。 |
$errors | object | この変数に値を代入すると、エンドポイントがエラーを返します。代入した値はレスポンスのmessage項目になります。 |
$http_code | int | この変数に値を代入すると、元のHTTPコードを上書きします。 |
利用可能なHTTPコード
| コード | 名称 | 意味 |
|---|---|---|
| 202 | Accepted | リクエストは受理されたが、処理はまだ完了していない |
| 204 | No Content | リクエストは成功したが、レスポンスボディを返さない |
| 400 | Bad Request | クライアントからのリクエストが不正 |
| 401 | Unauthorized | ユーザー認証が無い（未ログイン）ことによるリクエスト失敗 |
| 403 | Forbidden | コンテンツへのアクセス権が無いためにリクエスト失敗（401とは異なりユーザー認証は完了している） |
| 404 | Not Found | 指定されたエンドポイントのコンテンツが存在しないことによるリクエスト失敗 |
| 405 | Method Not Allowed | 許可されていないHTTPメソッドを使用した場合のエラー |
| 406 | Not Acceptable | リクエストの条件に合うレスポンスをサーバーが生成できない場合のエラー |
| 500 | Internal Server Error | クライアントからのリクエストは正しいが、サーバ側でエラーが発生した場合のエラー |
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}
request_api_post に使用できる変数
| 変数名 | 型 | 説明 |
|---|---|---|
$data | object | この変数に代入した値は、dataの項目でレスポンスされます。 |
$errors | object | この変数に値を代入すると、エンドポイントがエラーを返します。代入した値はレスポンスのmessage項目になります。 |
$http_code | int | この変数に値を代入すると、元のHTTPコードを上書きします。 |
利用可能なHTTPコード
| コード | 名称 | 意味 |
|---|---|---|
| 202 | Accepted | リクエストは受理されたが、処理はまだ完了していない |
| 204 | No Content | リクエストは成功したが、レスポンスボディを返さない |
| 400 | Bad Request | クライアントからのリクエストが不正 |
| 401 | Unauthorized | ユーザー認証が無い（未ログイン）ことによるリクエスト失敗 |
| 403 | Forbidden | コンテンツへのアクセス権が無いためにリクエスト失敗（401とは異なりユーザー認証は完了している） |
| 404 | Not Found | 指定されたエンドポイントのコンテンツが存在しないことによるリクエスト失敗 |
| 405 | Method Not Allowed | 許可されていないHTTPメソッドを使用した場合のエラー |
| 406 | Not Acceptable | リクエストの条件に合うレスポンスをサーバーが生成できない場合のエラー |
| 500 | Internal Server Error | クライアントからのリクエストは正しいが、サーバ側でエラーが発生した場合のエラー |
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"
}
実行結果（エラー）：
エラーメッセージがレスポンスされる事を確認できました。
エンベロープなしのJSONを返す（show_contents）
request_api/request_api_postのエンドポイントは、デフォルトではテンプレートでassignしたdata変数を{"data": ...}形式で返します。
エンドポイントの基本設定でshow_contentsを有効にすると、テンプレートが出力した文字列をJSONとして解釈し、その値がレスポンス全体になります（{"data": ...}のエンベロープなし）。
dataのエンベロープを付けずに、任意の形のJSONをそのまま返したい場合に利用できます。
エンドポイントの設定を変更する
エンドポイント一覧画面より、GETエンドポイントを作成するで作成したplain-custom-endpointの設定を開き、基本設定のshow_contentsを有効にしてエンドポイントを更新します。
カスタム処理の内容を変更する
show_contentsが有効の場合、テンプレートはJSONを直接出力する必要があります。
なお、{capture}は囲んだ内容をその場に出力せず変数（$smarty.capture.xxx）に格納できるタグで、利用は必須ではありませんが、show_contentsが無効の場合に独自のスタブを設定するチュートリアルのようにdata変数を組み立てる際に利用すると便利です。ただし、テンプレートが何も出力せずdata変数にassignするだけの書き方では、show_contentsを有効にするとテンプレートの出力が空になり、レスポンスは[]になります。
出力が空の場合は[]が返り、アプリケーションログにinfoログが記録されます。出力がJSONとして不正な場合はContents JSON errorのエラーになります。
カスタム処理の実行内容フィールドに下記を記載し、[更新する]をクリックします。
{literal}{"status":"ok","items":[1,2,3]}{/literal}
SwaggerUI画面からこのエンドポイントを実行すると、出力したJSONがそのままレスポンス全体として返されます。
{"status":"ok","items":[1,2,3]}
カスタム処理の実装例について
以上でカスタム処理とAPIエンドポイントの紐付け方法の紹介を終わります。 このチュートリアルではシンプルに紐付けの方法のみの説明にとどめましたが、カスタム処理の実装についてもっと詳しく知りたい場合は、下記ユースケース別のチュートリアルを参照してください。
- カスタム処理を利用して、APIエンドポイントに独自のスタブを設定する
- カスタム処理を利用して、APIに独自のバリデーションを実装する
- カスタム処理を利用して、APIのメイン処理に渡すリクエスト値を書き換える
関連ドキュメント
サポート
お探しのページは見つかりましたか？解決しない場合は、問い合わせフォームからお問い合わせいただくか、Slackコミュニティにご参加ください。