Although Lapis has comprehensive documentation, it might be hard to find aspecific thing if you don’t know where to look. Here are some commonly askedquestions organized on a single page suitable for searching.

All of these questions can easily be navigated to from the in-documentationsearch bar

If there’s a question that you think belongs here please open an issue on theissues tracker.

How do I read a HTTP header?

Thereq field of theself passed to actions has a headers fields with allthe request headers. They are normalized so you don’t have to be concernedabout capitalization.

locallapis=require("lapis")localapp=lapis.Application()app:match("/",function(self)returnself.req.headers["referrer"]end)

lapis=require"lapis"classAppextendslapis.Application"/":=>@req.headers["referrer"]

How do I write a HTTP header?

There are two ways to write headers. In these examples we set theAccess-Control-Allow-Origin header to*

You can return a headers field (or pass it towrite) from an action:

locallapis=require("lapis")localapp=lapis.Application()app:match("/",function(self)return{"OK",headers={["Access-Control-Allow-Origin"]="*"}}end)

lapis=require"lapis"classAppextendslapis.Application"/":=>"ok",{headers:{"Access-Control-Allow-Origin":"*"}}

Alternatively, theres field of theself has aheaders field that letsyou set headers.

locallapis=require("lapis")localapp=lapis.Application()app:match("/",function(self)self.res.headers["Access-Control-Allow-Origin"]="*"return"ok"end)

lapis=require"lapis"classAppextendslapis.Application"/":=>@res.headers["Access-Control-Allow-Origin"]="*""ok"

If you need to change the content type see below.

How do I set the content type?

Either manually set the header as described above, or use thecontent_typeoption of thewrite method, or action return value:

locallapis=require("lapis")localapp=lapis.Application()app:match("/",function(self)return{content_type="text/rss",[[<rss version="2.0"></rss>]]}end)

lapis=require"lapis"classAppextendslapis.Application"/":=>[[<rss version="2.0"></rss>]],content_type:"text/rss"

How to do I render JSON?

Use thejson option of thewrite method, or the action’s return value:

locallapis=require("lapis")localapp=lapis.Application()app:match("/",function(self)return{json={success=true,message="hello world"}}end)

lapis=require"lapis"classAppextendslapis.Application"/":=>{json:{success:truemessage:"hello world"}}

How can I read JSON HTTP body?

By default Lapis will only parse form-encoded request bodies. You can extract ajson encoded request body by using thejson_params action decorator function.The values are placed intoparams.

localjson_params=require("lapis.application").json_paramsapp:match("/json",json_params(function(self)returnself.params.valueend))

lapis=require"lapis"importjson_paramsfromrequire"lapis.application"classAppextendslapis.Application"/":json_params=>@params.value

Theapplication/json content type must be included in order for the data tobe extracted.

$curl\-H"Content-type: application/json"\-d'{"value": "hello"}'\'https://localhost:8080/json'

How do I respond to GET, POST, DELETE or other HTTP verbs?

Therespond_to action decorator function gives a basic framework for runningdifferent code depending on the HTTP method.

try_to_login is a hypothetical function, and not regularly globallyavailable

locallapis=require("lapis")localapp=lapis.Application()localrespond_to=require("lapis.application").respond_toapp:match("/",respond_to({-- do common setupbefore=function(self)ifself.session.current_userthenself:write({redirect_to="/"})endend,-- render the viewGET=function(self)return{render=true}end,-- handle the form submissionPOST=function(self)self.session.current_user=try_to_login(self.params.username,self.params.password)return{redirect_to="/"}end}))

lapis=require"lapis"importrespond_tofromrequire"lapis.application"classAppextendslapis.Application"/login":respond_to{before:=>-- do common setupif@session.current_user@writeredirect_to:"/"GET:=>-- render the viewrender:truePOST:=>-- handle the form submission@session.current_user=try_to_login(@params.username,@params.password)redirect_to:"/"}

How do I restart a running server, or reload the code?

Once the server is started, you can use thelapis term command from yourcommand line to stop the server.

If you're deploying new code, then you can hot-reload the code without anydowntime using thelapis build command.

How do I disable the stack trace on the error page?

By default Lapis will print the stack trace for any server errors. You canprevent this from happening by overriding thehandle_error method on yourapplication:

locallapis=require("lapis")localapp=lapis.Application()functionapp:handle_error(err,trace)return"There was an error"end

lapis=require"lapis"importrespond_tofromrequire"lapis.application"classAppextendslapis.Applicationhandle_error:(err,trace)=>"There was an error"

What versions of Lua are supported?

Lapis is tested against all versions of Lua (5.4 as of this guide). The defaultserver is OpenResty, which is tied to LuaJIT (which is a hybrid version ofLua5.1)

How do I handle multiple domains and subdomains?

Lapis doesn’t make any distinction between domains and subdomains. WithOpenResty you can use Nginx configurationlocation blocks to identifydifferent domains. Within the matched block you can execute the desired Lapisapplication.

How can I read the entire body of the request?

Lapis currently doesn’t provide a generalized interface for reading the rawbody or working with streaming large bodies. You will have to use the serverspecific interface.

For OpenResty andngx_lua: Load the body into memory by callingngx.req.read_body(). Next callngx.req.get_body_data() to get the contentsof the body.

If the body does not fit in to the size set by the Nginx configurationdirectiveclient_max_body_size then these functions will fail and returnnil.