Writing APIs

How to create API endpoints using Stormkit. API endpoints will be deployed to AWS Lambda.

Overview

You can create Node.js/TypeScript APIs using Stormkit. During deployment, your API functions are automatically packaged and deployed to AWS Lambda with filesystem-based routing.

Function timeouts are set at 15 seconds by default. If you require a different timeout, please inform us, and we can adjust it to suit your workflow.

How It Works

During build time, Stormkit:

1. Checks if there is a .stormkit/api folder
2. When found, uploads the folder to a Lambda function
3. The entry file takes the Request and calls the relevant file based on filesystem routing
4. Returns 404 if no matching route is found

Write and Deploy Your API

1. Create API directory

   Create an /api folder in the top level of your repository

2. Create endpoint file

   Create an /index.ts file in the /api folder

3. Export handler function

   Each file must export a default function with the signature shown below

4. Deploy

   Deploy your application. Stormkit will automatically build and deploy your API

Basic Example

api/index.ts

import http from 'http'

export default (req: http.IncomingMessage, res: http.ServerResponse) => {
  res.write('Function endpoint: /api')
  res.end()
}

api/user/subscribe.ts

import http from 'http'

export default (req: http.IncomingMessage, res: http.ServerResponse) => {
  res.write('Function endpoint: /api/user/subscribe')
  res.end()
}

Filesystem Routing

The table below shows how the API routing works:

+ /api
  - index.ts        // /api
  + /users
    - index.ts      // /api/users
    - subscribe.ts  // /api/users/subscribe
    - create.ts     // /api/users/create
    + /[id]
      - remove.ts   // /api/users/:id/remove (where :id is a placeholder for dynamic values)

For more details on how the filesystem routing works, check the source code of the matchPath function.

Now go ahead and deploy your application. When Stormkit detects an /api source folder, it checks whether it is already built or not. If the /api folder is not yet built, Stormkit tries to build your API using Webpack and then deploys the output to the lambda function. This process is automatic.

Routing Features

Dynamic Routes

Use square brackets for dynamic segments:

/api/users/[id]/index.ts       // Matches /api/users/123
/api/posts/[slug]/comments.ts  // Matches /api/posts/hello-world/comments

api/users/[id]/index.ts

import http from 'http'

export default (req: http.IncomingMessage, res: http.ServerResponse) => {
  // Extract ID from URL
  const id = req.url?.split('/')[3]; // /api/users/:id
  res.write(`User ID: ${id}`)
  res.end()
}

Matching by Request Method

By default, files are matched through all requests. If you want to restrict certain endpoints with a request method, you can specify the method in the file name, right before the extension:

+ /api
  - index.ts            // ALL /api
  + /users
    - index.get.ts      // GET /api/users
    - index.post.ts     // POST /api/users
    - subscribe.ts      // ALL /api/users/subscribe
    + /[id]
      - index.delete.ts // DELETE /api/users/:id

GET Requests

index.get.ts - Only handles GET requests

POST Requests

index.post.ts - Only handles POST requests

PUT Requests

index.put.ts - Only handles PUT requests

DELETE Requests

index.delete.ts - Only handles DELETE requests

Ignore Certain Files

If a file name starts with an underscore (_), the file won’t be matched. If the directory starts with an underscore (_), the whole subdirectory tree will be ignored. This is useful to organize helper methods in different files.

+ /api
  - index.ts
  - _helpers.ts          // Ignored
  + /_utils              // Entire directory ignored
    - validation.ts
    - auth.ts
  + /users
    - index.ts
    - _user-model.ts     // Ignored

Working with Request Data

Reading Request Body

api/users/create.post.ts

import http from 'http'

export default (req: http.IncomingMessage, res: http.ServerResponse) => {
  let body = '';
  
  req.on('data', chunk => {
    body += chunk.toString();
  });
  
  req.on('end', () => {
    const data = JSON.parse(body);
    // Process data
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.write(JSON.stringify({ success: true, data }));
    res.end();
  });
}

Query Parameters

api/search.ts

import http from 'http'
import { URL } from 'url'

export default (req: http.IncomingMessage, res: http.ServerResponse) => {
  const url = new URL(req.url || '', `http://${req.headers.host}`);
  const query = url.searchParams.get('q');
  
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.write(JSON.stringify({ query }));
  res.end();
}

Custom Builds

If your source code contains more complex use cases and Stormkit fails to build, you can build the source code yourself. Here’s the webpack config Stormkit uses to build the API. You can copy this and extend it based on your needs.

webpack.config.ts

import type { Configuration } from 'webpack'
import * as webpack from 'webpack'
import * as path from 'path'
import * as dotenv from 'dotenv'
import { glob } from 'glob'

const config: Configuration = {
  mode: 'production',
  target: 'node',

  // Iterate over the `api` subfolder and create an entry file
  // for each `.ts` file. This will tell webpack to create a bundle
  // for each function.
  entry: glob.sync('./api/**/*.{js,ts,tsx}').reduce((acc, file) => {
    acc[file.replace(/^\.?\/api\//, '').split('.ts')[0]] = file
    return acc
  }, {}),

  output: {
    filename: '[name].js',
    // Build into `.stormkit/api` - Stormkit will take care of the rest.
    path: path.resolve(__dirname, '.stormkit/api'),
    // We need to use commonjs so that webpack exports the functions.
    library: {
      type: 'commonjs',
    },
  },

  module: {
    rules: [
      {
        test: /\.ts$/,
        loader: 'ts-loader',
        options: {
          compilerOptions: {
            noEmit: false,
          },
        },
      },
    ],
  },

  resolve: {
    extensions: ['.tsx', '.ts', '.js'],
  },

  // Inject .env variables into the bundles.
  plugins: [
    new webpack.DefinePlugin(
      Object.keys(dotenv.config() || {}).reduce((obj, key) => {
        obj[`process.env.${key}`] = JSON.stringify(process.env[key])
        return obj
      }, {})
    ),
  ],
}

export default config

Testing Locally

In order to test the API locally, install the @stormkit/cli package.

1. Install CLI

   npm i -D @stormkit/cli
   
2. Update package.json

   package.json

   {
     "scripts": {
       "dev:api": "stormkit api"
     }
   }
   
3. Run development server

   npm run dev:api
   
4. Access API

   You can access the API from http://localhost:9090/api

API in Action

If you wish to see the API in action promptly, take a look at our template project, utilizing Vite.js as the build tool. This project encapsulates server-side rendering (SSR), API functionality, and a single-page application.

Best Practices

• Use TypeScript - Type safety helps catch errors early
• Validate inputs - Always validate request data
• Handle errors - Use try-catch blocks and return appropriate error codes
• Keep functions focused - Each endpoint should do one thing well
• Use helper files - Organize shared code in _helpers.ts files
• Set proper headers - Always set Content-Type and other relevant headers
• Environment variables - Use env vars for configuration and secrets
• Test locally - Use @stormkit/cli to test before deploying