HTTPエンドポイント

エンドポイント（http.endpoint）はLua関数を実行するHTTPルートハンドラを定義します。

定義

- name: get_user
  kind: http.endpoint
  meta:
    router: app:api_router
  method: GET
  path: /users/{id}
  func: app.users:get_user

設定

フィールド 型 必須 説明
meta.router registry.ID いいえ 親ルーター（ルーターが1つだけ登録されている場合はそれがデフォルト）
method string はい HTTPメソッド
path string はい URLパスパターン
func registry.ID はい 実行する関数

HTTPメソッド

サポートされるメソッド：

メソッド ユースケース
GET リソースの取得
POST リソースの作成
PUT リソースの置換
PATCH 部分更新
DELETE リソースの削除
HEAD ヘッダーのみ
OPTIONS CORSプリフライト（自動処理）
TRACE 診断ループバック

パスパラメータ

URLパラメータには{param}構文を使用：

- name: get_user
  kind: http.endpoint
  method: GET
  path: /users/{id}
  func: get_user

- name: get_user_post
  kind: http.endpoint
  method: GET
  path: /users/{user_id}/posts/{post_id}
  func: get_user_post

ハンドラでのアクセス：

local http = require("http")

local function handler()
    local req = http.request()
    local user_id = req:param("id")
    local post_id = req:param("post_id")
end

ワイルドカードパス

{path...}で残りのパスをキャプチャ：

- name: file_handler
  kind: http.endpoint
  method: GET
  path: /files/{path...}
  func: serve_file

local function handler()
    local req = http.request()
    local file_path = req:param("path")
    -- /files/docs/readme.md -> path = "docs/readme.md"
end

ハンドラ関数

エンドポイント関数はhttpモジュールからリクエストとレスポンスオブジェクトを取得します：

local http = require("http")
local json = require("json")

local function handler()
    local req = http.request()
    local res = http.response()

    -- リクエストを読み取り
    local body = req:body()
    local user_id = req:param("id")
    local page = req:query("page")
    local auth = req:header("Authorization")

    -- 処理
    local user = get_user(user_id)

    -- レスポンスを書き込み
    res:set_content_type(http.CONTENT.JSON)
    res:set_status(http.STATUS.OK)
    res:write_json(user)
end

return { handler = handler }

リクエストオブジェクト

メソッド 戻り値 説明
req:method() string HTTPメソッド
req:path() string リクエストパス
req:param(name) string URLパラメータ
req:params() table すべてのパスパラメータ
req:query(name) string クエリパラメータ
req:query_params() table すべてのクエリパラメータ
req:header(name) string リクエストヘッダー
req:body() string リクエストボディ
req:body_json() table, error JSONボディをパース
req:has_body() boolean ボディの有無を確認
req:content_type() string コンテンツタイプ
req:content_length() number ボディサイズ（バイト）
req:host() string ホスト名
req:remote_addr() string クライアントIPアドレス
req:accepts(type) boolean コンテンツネゴシエーション
req:is_content_type(type) boolean コンテンツタイプを確認
req:stream() Stream 大きなファイル用のストリームとしてボディを取得
req:parse_multipart(max?) table, error マルチパートフォームをパース

レスポンスオブジェクト

メソッド 説明
res:set_status(code) HTTPステータスコードを設定
res:set_header(name, value) レスポンスヘッダーを設定
res:set_content_type(type) コンテンツタイプを設定
res:write(data) 生のボディを書き込み
res:write_json(data) JSONレスポンスを書き込み
res:write_event(data) SSEイベントを送信
res:set_transfer(encoding) 転送モードを設定（SSE、chunked）
res:flush() レスポンスをクライアントにフラッシュ

JSON APIパターン

JSON APIの一般的なパターン：

local http = require("http")

local function handler()
    local req = http.request()
    local res = http.response()

    local data, err = req:body_json()
    if err then
        res:set_status(http.STATUS.BAD_REQUEST)
        res:write_json({error = "Invalid JSON"})
        return
    end

    local result = process(data)

    res:set_status(http.STATUS.OK)
    res:write_json(result)
end

return { handler = handler }

エラーレスポンス

local http = require("http")

local function api_error(res, status, code, message)
    res:set_status(status)
    res:write_json({
        error = {
            code = code,
            message = message
        }
    })
end

local function handler()
    local req = http.request()
    local res = http.response()

    local user_id = req:param("id")
    local user, err = db.get_user(user_id)

    if err then
        if errors.is(err, errors.NOT_FOUND) then
            return api_error(res, http.STATUS.NOT_FOUND, "USER_NOT_FOUND", "User not found")
        end
        return api_error(res, http.STATUS.INTERNAL_ERROR, "INTERNAL_ERROR", "Server error")
    end

    res:set_status(http.STATUS.OK)
    res:write_json(user)
end

return { handler = handler }

例

CRUDエンドポイント

entries:
  - name: users_router
    kind: http.router
    prefix: /api/users
    middleware:
      - cors
      - compress

  - name: list_users
    kind: http.endpoint
    meta:
      router: users_router
    method: GET
    path: /
    func: app.users:list

  - name: get_user
    kind: http.endpoint
    meta:
      router: users_router
    method: GET
    path: /{id}
    func: app.users:get

  - name: create_user
    kind: http.endpoint
    meta:
      router: users_router
    method: POST
    path: /
    func: app.users:create

  - name: update_user
    kind: http.endpoint
    meta:
      router: users_router
    method: PUT
    path: /{id}
    func: app.users:update

  - name: delete_user
    kind: http.endpoint
    meta:
      router: users_router
    method: DELETE
    path: /{id}
    func: app.users:delete

保護されたエンドポイント

- name: admin_endpoint
  kind: http.endpoint
  meta:
    router: admin_router
  method: POST
  path: /settings
  func: app.admin:update_settings
  post_middleware:
    - endpoint_firewall
  post_options:
    endpoint_firewall.action: "admin"

関連項目