app.url - URL Parsing and Building API

URL parsing, building, and encoding operations.

Permission level: L0 (safe, always available)

Methods

app.url.parse(urlString)

Parses a URL into a components table.

Parameters:

• urlString (string) - URL string

Returns: table, error - URL components

local url = app.url.parse("https://user:pass@example.com:8080/path?q=test&lang=zh#section")
-- {
--   scheme = "https",
--   host = "example.com",
--   port = 8080,
--   path = "/path",
--   query = "q=test&lang=zh",
--   fragment = "section",
--   user = "user",
--   password = "pass",
--   queryParams = {q = "test", lang = "zh"}
-- }

app.url.build(components)

Builds a URL from a components table.

Parameters:

• components (table) - URL components (supported fields are the same as parse() return value)

Returns: string, error

local url = app.url.build({
    scheme = "https",
    host = "api.example.com",
    path = "/v1/search",
    queryParams = {q = "hello", page = "1"}
})
-- "https://api.example.com/v1/search?page=1&q=hello"

app.url.encodeQuery(params)

Encodes a parameter table into a query string.

Parameters:

• params (table) - Key-value pairs

Returns: string - Encoded query string (without ?)

local qs = app.url.encodeQuery({name = "John", age = "30"})
-- "age=30&name=John"

app.url.decodeQuery(queryString)

Decodes a query string into a parameter table.

Parameters:

• queryString (string) - Query string (may include a leading ?)

Returns: table

local params = app.url.decodeQuery("?name=%E5%BC%A0%E4%B8%89&age=30")
-- {name = "张三", age = "30"}

app.url.encode(str)

URL-encodes a string.

Parameters:

• str (string) - Original string

Returns: string

local encoded = app.url.encode("hello world/你好")

app.url.decode(str)

URL-decodes a string.

Parameters:

• str (string) - Encoded string

Returns: string

local decoded = app.url.decode("hello%20world")  -- "hello world"

Examples

Building an API Request URL

function MyPlugin:buildAPIUrl(endpoint, params)
    return app.url.build({
        scheme = "https",
        host = "api.example.com",
        path = "/v2/" .. endpoint,
        queryParams = params
    })
end

local url = self:buildAPIUrl("search", {q = "test", limit = "10"})
local result = app.http.get(url)