The API tries to leverage as much of the web standards as is possible as well as tries to be simple and straightforward.

    To start a HTTP server on a given port, you can use the serve function from . This function takes a handler function that will be called for each incoming request, and is expected to return a response (or a promise resolving to a response).

    Here is an example of a handler function that returns a “Hello, World!” response for each request:

    ℹ️ The handler can also return a Promise<Response>, which means it can be an async function.

    To then listen on a port and handle requests you need to call the serve function from the https://deno.land/std@$STD_VERSION/http/server.ts module, passing in the handler as the first argument:

    1. import { serve } from "https://deno.land/std@$STD_VERSION/http/server.ts";
    3. serve(handler);

    By default serve will listen on port 8000, but this can be changed by passing in a port number in the second argument options bag:

    Inspecting the incoming request

    Most servers will not answer with the same response for every request. Instead they will change their answer depending on various aspects of the request: the HTTP method, the headers, the path, or the body contents.

    The request is passed in as the first argument to the handler function. Here is an example showing how to extract various parts of the request:

    1. async function handler(req: Request): Promise<Response> {
    2.   console.log("Method:", req.method);
    4.   const url = new URL(req.url);
    5.   console.log("Path:", url.pathname);
    6.   console.log("Query parameters:", url.searchParams);
    9.   if (req.body) {
    10.     const body = await req.text();
    11.     console.log("Body:", body);
    12.   }
    14.   return new Response("Hello, World!");
    15. }

    Most servers also do not respond with “Hello, World!” to every request. Instead they might respond with different headers, status codes, and body contents (even body streams).

    Here is an example of returning a response with a 404 status code, a JSON body, and a custom header:

    Response bodies can also be streams. Here is an example of a response that returns a stream of “Hello, World!” repeated every second:

    1. function handler(req: Request): Response {
    2.   let timer;
    3.   const body = new ReadableStream({
    4.     async start(controller) {
    5.       timer = setInterval(() => {
    6.         controller.enqueue("Hello, World!\n");
    7.       }, 1000);
    8.     },
    9.       clearInterval(timer);
    10.     },
    11.   });
    12.   return new Response(body, {
    13.     headers: {
    14.       "content-type": "text/plain; charset=utf-8",
    15.     },
    17. }

    ℹ️ Note the cancel function here. This is called when the client hangs up the connection. This is important to make sure that you handle this case, as otherwise the server will keep queuing up messages forever, and eventually run out of memory.

    WebSocket support

    Deno can upgrade incoming HTTP requests to a WebSocket. This allows you to handle WebSocket endpoints on your HTTP servers.

    To upgrade an incoming Request to a WebSocket you use the Deno.upgradeWebSocket function. This returns an object consisting of a Response and a web standard WebSocket object. This response must be returned from the handler for the upgrade to happen. If this is not done, no WebSocket upgrade will take place.

    Because the WebSocket protocol is symmetrical, the WebSocket object is identical to the one that can be used for client side communication. Documentation for it can be found on MDN.

    WebSockets are only supported on HTTP/1.1 for now. The connection the WebSocket was created on can not be used for HTTP traffic after a WebSocket upgrade has been performed.

    ℹ️ To use HTTPS, you will need a valid TLS certificate and a private key for your server.

    To use HTTPS, use serveTls from the https://deno.land/std@$STD_VERSION/http/server.ts module instead of serve. This takes two extra arguments in the options bag: certFile and keyFile. These are paths to the certificate and key files, respectively.

    1. import { serveTls } from "https://deno.land/std@$STD_VERSION/http/server.ts";
    3. serveTls(handler, {
    4.   port: 443,
    5.   certFile: "./cert.pem",
    6.   keyFile: "./key.pem",
    7. });

    Lower level HTTP server APIs

    If you do want to learn more about the low level HTTP server APIs though, you can read more about them here.