express

@stl-api/express: Express integration for Stainless API

Use this package to serve a Stainless API in an Express app.

Table of Contents

• @stl-api/express: Express integration for Stainless API
• Table of Contents
• Getting started
  • Installation
  • Creating an Express Router
    • From an entire Stainless API
      • Options
      • Notes
    • From a Stainless Resource
      • Options
      • Notes
  • Lower-level APIs
    • Create an Express request handler
      • Options
      • Notes
    • Call a Stainless API endpoint from an Express handler
    • Parse request from an Express handler
  • Type Reference
    • AddEndpointsToExpressOptions
      • basePathMap?: Record<string, string>
      • handleErrors?: boolean (default: true)
      • addMethodNotAllowedHandlers?: boolean (default: true)
    • AddToExpressOptions
      • basePathMap?: Record<string, string>
      • handleErrors?: boolean (default: true)

Getting started

Warning

This is alpha software, and we may make significant changes in the coming months. We're eager for you to try it out and let us know what you think!

Installation

npm i --save 'stainless-api/stl-api#express-0.0.3'

Creating an Express Router

From an entire Stainless API

apiRouter(
  api: AnyAPIDescription,
  options?: AddEndpointsToExpressOptions
): Router

import { apiRouter } from "@stl-api/express";
import express from "express";
import api from "./api";

const app = express();
app.use(apiRouter(api));

Options

See AddEndpointsToExpressOptions.

Notes

apiRouter is provided as a convenience; for production use cases you'll probably want to use more fine-grained methods below that enable greater customization.

apiRouter installs default json, text and raw middleware on the router:

router.use(express.json());
router.use(express.text());
router.use(express.raw());

From a Stainless Resource

resourceRouter(
  resource: Pick<AnyResourceConfig, "actions" | "namespacedResources">,
  options?: AddEndpointsToExpressOptions & RouterOptions
): Router

import { resourceRouter } from "@stl-api/express";
import express from "express";
import posts from "./posts";

const app = express();
app.use(resourceRouter(posts));

Options

See AddEndpointsToExpressOptions.

Notes

resourceRouter is provided as a convenience; for production use cases you'll probably want to use more fine-grained methods below that enable greater customization.

resourceRouter installs default json, text and raw middleware on the router:

router.use(express.json());
router.use(express.text());
router.use(express.raw());

Lower-level APIs

Create an Express request handler

stlExpressRouteHandler(
  endpoint: AnyEndpoint,
  options: CreateExpressHandlerOptions
): RequestHandler

import express from "express";
import { stlExpressRouteHandler } from "@stl-api/express";
import retrievePosts from "./posts/retrieve";

export const app = express();

app.get(
  "/api/posts/:postId",
  express.json(),
  stlExpressRouteHandler(retrievePosts)
);

Options

See AddToExpressOptions.

Notes

By default stlExpressRouteHandler will handle all errors on the route. If you want to customize error handling you may want to pass the handleErrors: false option.

Call a Stainless API endpoint from an Express handler

stlExecuteExpressRequest<EC extends AnyEndpoint>(
  endpoint: AnyEndpoint,
  req: Request,
  res: Response
): Promise<EndpointResponseOutput<EC>>

import express, { Request, Response } from "express";
import { stlExecuteExpressRequest } from "@stl-api/express";
import retrievePosts from "./posts/retrieve";

export const app = express();

app.get("/api/posts/:postId", express.json(), (req: Request, res: Response) => {
  const response = await stlExecuteExpressRequest(retrievePosts, req, res);
  res.status(200).json(response);
});

Parse request from an Express handler

stlPrepareExpressRequest<EC extends AnyEndpoint>(
  endpoint: AnyEndpoint,
  req: Request,
  res: Response
): Promise<[RequestData<EC["path"], EC["query"], EC["body"]>, StlContext<EC>]>

import express, { Request, Response } from "express";
import { stlPrepareExpressRequest } from "@stl-api/express";
import retrievePosts from "./posts/retrieve";
import prisma from "../libs/prismadb";

export const app = express();

app.get("/api/posts/:postId", express.json(), (req: Request, res: Response) => {
  const [{ postId }, stlContext] = await stlPrepareExpressRequest(
    retrievePosts,
    req,
    res
  );
  const post = await prisma.posts.findUniqueOrThrow({ where: { id: postId } });
  const repsonse = await retrievePosts.response.parseAsync(responseInput, {
    stlContext,
  });
  res.status(200).json(response);
});

Type Reference

AddEndpointsToExpressOptions

basePathMap?: Record<string, string>

Mappings to apply to Stainless API Endpoint paths. For example with basePathMap: { '/api/', '/api/v2/' }, the endpoint GET /api/postswould GET transformed to GET /api/v2/posts`

handleErrors?: boolean (default: true)

If false, errors will be passed to the next middleware; otherwise the created express handler will send the appropriate response if an error is caught.

addMethodNotAllowedHandlers?: boolean (default: true)

Whether to add 405 method not allowed handlers to the Express Router or Application

AddToExpressOptions

basePathMap?: Record<string, string>

Mappings to apply to Stainless API Endpoint paths. For example with basePathMap: { '/api/', '/api/v2/' }, the endpoint GET /api/postswould get transformed to GET /api/v2/posts`

handleErrors?: boolean (default: true)

If false, errors will be passed to the next middleware; otherwise the created express handler will send the appropriate response if an error is caught.