Custom Request Handlers

As an API gateway, the Request Handler is the most important part of a zup. A request handler is a module with an export that fulfills the following type definition (typescript):

export type RequestHandler = (
  request: ZuploRequest,
  context: ZuploContext,
) => Promise<any>;

An example implementation is provided in the default module template (when you add a new module):

import { ZuploRequest, ZuploContext } from "@zuplo/runtime";
 
export default async function (request: ZuploRequest, context: ZuploContext) {
  return "What zup?";
}

This is a request handler that receives a request (of type ZuploRequest - more on this interface here) and returns a response of type string. You can return any type from a Request Handler and Zuplo will auto-serialize the response to JSON and add a content-type header to your response of application/json. This makes it very easy to build simple JSON APIs.

Parameters & Query strings#

You can read parameters specified on the route path as follows:

Route = /foos/:foo/bars/:bar

This route has two parameters foo and bar. They can be accessed in the request handler on the request.params object:

// GET root/foos/123/bars/car
export default async function (request: ZuploRequest, context: ZuploContext) {
  return request.params.foo + request.params.bar;
}
 
// returns 123car

You can read query strings as follows:

URL = /foos?productId=xkcd&carId=1234

// GET /foos?productId=xkcd&carId=1234
export default async function (request: ZuploRequest, context: ZuploContext) {
  return request.query.productId + request.query.carId;
}
 
// returns xkcd1234

Reading the body#

The ZuploRequest object inherits from the web standards Request object. You can read about it on MDN here: https://developer.mozilla.org/en-US/docs/Web/API/Request

The Request type has three properties that allow access to the incoming body of the request. The body property is of type ReadableStream and is the most efficient way to reuse a body in an outgoing request.

If you want to read the body you have two options:

await request.text() - this method reads the full body into a string.
await request.json() - this method reads the body and performs a JSON.parse() to read the body into an object in memory. Use only if you’re confident the body is well-formed JSON (consider pre-validation with the Validation Policy).

Response Class#

If you want more control over the response you can return an instance of the Response class.

The Response class is also from web standards - you can read about it on MDN here: https://developer.mozilla.org/en-US/docs/Web/API/Response

Here's an example

import { ZuploRequest, ZuploContext } from "@zuplo/runtime";
 
export default async function (request: ZuploRequest, context: ZuploContext) {
  const response = new Response(`<html><body>What zup?</body></html>`, {
    status: 200,
    headers: {
      "content-type": "text/html",
    },
  });
  return response;
}