Hosting Static HTML Pages Using AWS Lambda and API Gateway

AWS Lambda and API Gateway are commonly used to create microservice JSON endpoints. In such applications, the static html content is usually stored in an S3 bucket. However if you are building a quick AWS lambda microservice prototype, it would be simpler to render static HTML from a lambda function. This has a number of advantages.

  • We just need one Java project containing all lambda functions and the static content.
  • We can host the microservice endpoints and static html on the same domain created by API gateway without any further configuration.

How to Host HTML Pages Using AWS Lambda and API Gateway

The following tutorial contains step by step instructions for hosting static html content using AWS lambda and API gateway. AWS lambda supports multiple language runtimes. The following sample code is written in Java and uses the AWS Java API.

The following lambda function reads an html file from the classpath and then prints it to the response object. Note that if you are building your Java project using Maven (which I highly recommend), this html file should be copied to src/main/resources folder.

package com.quickprogrammingtips.lambda;


import com.amazonaws.util.IOUtils;

// Render static HTML from AWS Lambda function 
public class ShowHtmlLambdaHandler implements RequestStreamHandler {

	public void handleRequest(InputStream is, OutputStream os, Context context) throws IOException {
        context.getLogger().log("Displaying html content" );
        try {
    		ClassLoader loader = ShowHtmlLambdaHandler.class.getClassLoader();
    		try(InputStream resourceStream = loader.getResourceAsStream("hello.html")) {
        }catch(Exception ex) {
        	os.write("Error in generating output.".getBytes());

The following maven pom.xml contains the minimum dependencies for the above implementation. Use this pom file if you want to minimize the size of the fat jar uploaded to AWS lambda. Note the use of maven shade plugin to embed dependent jars in the final fat jar. if you don't use shade plugin, you will get ClassNotFoundException when you run the lambda function in AWS.

<project xmlns="" xmlns:xsi=""





Following is the content of the hello.html file,

		<title>Hello World!</title>
		<h1>Hello World!</h1>

Build the project using the maven package command (ensure that you have maven installed and available on system path in your machine),

mvn package

Upload the htmllambda-0.0.1-SNAPSHOT.jar created in target folder to AWS lambda as shown below. This assumes that a basic lambda role is already created using AWS IAM console. Ensure that this role (lambda_basic_execution) has at least the predefined policy AWSLambdaBasicExecutionRole attached to it. Once lambda function is created, click on the Test button to verify the html output.



We can now configure a simple API gateway endpoint to use the above lambda function to output static html.

From API gateway, click on Create API. Name the new API as htmldemo. From Actions menu, click on Create Method and select GET. Select the region where lambda is hosted and select the lambda function as shown below. Click Save.


From Actions menu, click on Deploy API. Whenever any change is made to the API configuration, it needs to be deployed before it is available at the URL endpoint. This allows us to deploy different configurations to different stages (production, staging, qa etc.). When you deploying for the first time, you need to create a stage. Give it a name beta. This will enable the API on a public URL as shown below,


Click on the URL to open it in a browser window.


Browser renders our hello world html as raw text! This is due to the default JSON content type set by API gateway. Also note that our content has double quotes around it. Let us now modify API gateway configuration to remove double quotes and set our content type as html.

Click on GET under resources for htmldemo API. Click on Method Response on the right window. Remove application/json entry and then add Content-Type header as shown below.


Click on GET under resources for htmldemo API. Click on Integration Response on the right window. Under Header Mappings, configure mapping value for Content Type as 'text/html'. Please note that single quotes must be preserved in the text. Under Body Mapping Templates, remove application/json and then add text/html with the following template content,



Now deploy the changed configuration. From Actions menu, click on Deploy API and deploy it to the beta stage we created earlier. Wait for a few seconds and then click on the API URL. If everything goes well, you should see the Hello World! output (beware of the browser cache!) in the browser.