HTTP-Endpunkte

Endpunkte (http.endpoint) definieren HTTP-Routen-Handler, die Lua-Funktionen ausführen.

Definition

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

Konfiguration

Feld Typ Erforderlich Beschreibung
meta.router registry.ID Nein Übergeordneter Router (Standard: der einzige Router, falls genau einer registriert ist)
method string Ja HTTP-Methode
path string Ja URL-Pfadmuster
func registry.ID Ja Auszuführende Funktion

HTTP-Methoden

Unterstützte Methoden:

Methode Anwendungsfall
GET Ressourcen abrufen
POST Ressourcen erstellen
PUT Ressourcen ersetzen
PATCH Teilweise aktualisieren
DELETE Ressourcen entfernen
HEAD Nur Header
OPTIONS CORS-Preflight (automatisch behandelt)
TRACE Diagnostischer Loopback

Pfadparameter

Verwenden Sie {param}-Syntax für URL-Parameter:

- 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

Zugriff im Handler:

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

Wildcard-Pfade

Verbleibenden Pfad mit {path...} erfassen:

- 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

Handler-Funktion

Endpunkt-Funktionen erhalten Request- und Response-Objekte aus dem http-Modul:

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

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

    -- Request lesen
    local body = req:body()
    local user_id = req:param("id")
    local page = req:query("page")
    local auth = req:header("Authorization")

    -- Verarbeiten
    local user = get_user(user_id)

    -- Response schreiben
    res:set_content_type(http.CONTENT.JSON)
    res:set_status(http.STATUS.OK)
    res:write_json(user)
end

return { handler = handler }

Request-Objekt

Methode Rückgabe Beschreibung
req:method() string HTTP-Methode
req:path() string Request-Pfad
req:param(name) string URL-Parameter
req:params() table Alle Pfadparameter
req:query(name) string Query-Parameter
req:query_params() table Alle Query-Parameter
req:header(name) string Request-Header
req:body() string Request-Body
req:body_json() table, error JSON-Body parsen
req:has_body() boolean Prüfen, ob Body vorhanden
req:content_type() string Content-Type
req:content_length() number Body-Größe in Bytes
req:host() string Hostname
req:remote_addr() string Client-IP-Adresse
req:accepts(type) boolean Content Negotiation
req:is_content_type(type) boolean Content-Type prüfen
req:stream() Stream Body als Stream für große Dateien
req:parse_multipart(max?) table, error Multipart-Formular parsen

Response-Objekt

Methode Beschreibung
res:set_status(code) HTTP-Statuscode setzen
res:set_header(name, value) Response-Header setzen
res:set_content_type(type) Content-Type setzen
res:write(data) Raw-Body schreiben
res:write_json(data) JSON-Response schreiben
res:write_event(data) SSE-Event senden
res:set_transfer(encoding) Transfer-Modus setzen (SSE, chunked)
res:flush() Response an Client übertragen

JSON-API-Muster

Gängiges Muster für JSON-APIs:

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 }

Fehler-Responses

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 }

Beispiele

CRUD-Endpunkte

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

Geschützter Endpunkt

- 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"

Siehe auch