前回の(1)はこちらから。
パラメータの操作
(2)の本節では、パラメータの操作方法を説明します。
paramsでパラメータの検証
パラメータを検証するにはparams
を、強制オプションを定義するにはrequires
を使います。
次の例では、ユーザーを追加するAPIにusers
パラメータを必須として定義しています。
必須ではないパラメータはoptional
で宣言できます。regex
を使うと正規表現で形式を指定できます。
空のJSONをPOSTすると、users
がないためエラーを返却できていることが確認できます。エラーメッセージも自動で返却されます。
エラーログにも警告メッセージが自動で表示されます。ステータスコード400(Bad Request)で返却できていることを確認できます。
include_missingですべてのパラメータの取得
すべてのパラメータを取得するにはinclude_missing
を使います。デフォルトでは値のないパラメータは取得できないため注意してください。
route_paramでルートパラメータの取得
ルートパラメータを取得するにはroute_param
を使用します。何も指定しない場合はどんな値でも入るため、requires
を使用した強制オプションの定義を推奨します。
実行タイミングの操作
任意のタイミングで処理を実行するにはhooks
を使います。実行される順番から、before
、before_validation
、after_validation
、after
の4種が存在します。
beforeでAPIの実行前に処理実行
APIの実行前に処理を実行したい場合はbefore
、before_validation
を使います。before
のあとにbefore_validation
が実行されます。実行タイミング以外の違いはありません。
次の例では、ログを出力できるプラグインRaisin::Logger
を使って、APIの実行時にリクエスト内容をログに出力しています。
APIを実行すると、ログに出力されていることが確認できます。
afterでAPIの実行後に処理実行
APIの実行後に処理を実行したい場合はafter
、after_validation
を使います。after_validation
のあとにafter
が実行されます。実行タイミング以外の違いはありません。before
とは違ってAPIが正常終了しないと呼び出されない点に注意してください。
次の例では、APIの実行完了時に成功メッセージをログに出力しています。
存在しないエンドポイントを指定してAPIが正常に終了しなかった場合は、ログに出力されていないことが確認できます。
便利モジュール
本節では、Raisinを使ううえで便利なモジュールを説明します。
Raisin::Plugin::SwaggerでAPIドキュメントの作成
HTML形式でドキュメントを生成できるSwagger UIのためのJSONを生成するには、Raisin::Plugin::Swagger
を使います。生成されたJSONをSwagger UIで読み込むと、ドキュメントを自動生成できます。
使用するには、APIの中でSwaggerのプラグインを有効にします。
/swagger.json
にアクセスすると、Swagger UI用のJSONが返ってくることが確認できます。このJSONをSwagger UIで読み込むと、図1のようにAPIドキュメントを確認できます。
Plack::TestでAPIのテストの実施
RaisinはPlackに準拠しているため、Plack::Test
モジュールでテストを行えます。
先ほどのAPIのテストの例を記述します。
レスポンスコードのチェックとJSONの文字列をチェックします。
失敗したテストでは、期待値と実際に受け取った値を確認できます。
まとめ
本稿では、Rest APIマイクロフレームワークであるRaisinを使ったRest APIの作成方法について解説しました。Raisinはマイクロフレームワークながら、APIドキュメントの生成などAPI開発に欠かせない機能を兼ね備えている強力なフレームワークです。
本稿で紹介したものは一部にすぎません。セッション管理や、Moose
と組み合わせると型制約の使用もできます。みなさんも、PerlでRest APIを作成する際はRaisinを試してください。
さて、次回の執筆者は小林謙太さんで、テーマは「ISUCON11の実装から最近のPerlを学ぶ」です。お楽しみに。
- 特集1
イミュータブルデータモデルで始める
実践データモデリング
業務の複雑さをシンプルに表現!
- 特集2
いまはじめるFlutter
iOS/Android両対応アプリを開発してみよう
- 特集3
作って学ぶWeb3
ブロックチェーン、スマートコントラクト、NFT