APIs

Nitric provides a simple and powerful way to build HTTP APIs in your applications. The api resource allows you to create APIs with routing, middleware, request handlers, and security features.

Quick Start

Here's a minimal example to get you started:

import { api } from '@nitric/sdk'

const myApi = api('my-api')

myApi.get('/hello', async (ctx) => {
  ctx.res.body = 'Hello World!'
})

Core Concepts

API Resources

Each API in your application needs a unique name. This name is used to identify the API across your project and in cloud deployments.

const myApi = api('my-api-name')

Request Context

Every handler receives a context object (ctx) that contains:

req: The incoming request object
res: The response object you'll use to send data back

Routing

APIs support all standard HTTP methods and path-based routing:

const myApi = api('my-api')

// GET /items
myApi.get('/items', async (ctx) => {
  ctx.res.json({ items: [] })
})

// POST /items
myApi.post('/items', async (ctx) => {
  const item = ctx.req.json()
  ctx.res.status = 201
  ctx.res.json(item)
})

// PUT /items/:id
myApi.put('/items/:id', async (ctx) => {
  const { id } = ctx.req.params
  const item = ctx.req.json()
  ctx.res.json({ id, ...item })
})

Path Parameters

You can define dynamic routes using path parameters:

myApi.get('/users/:id', async (ctx) => {
  const { id } = ctx.req.params
  ctx.res.json({ id })
})

Advanced Features

Middleware

Middleware allows you to add common functionality across routes. Each middleware receives the context and a next function to continue the request chain:

async function authMiddleware(ctx, next) {
  const token = ctx.req.headers['authorization']
  if (!token) {
    ctx.res.status = 401
    return ctx
  }
  return await next(ctx)
}

const secureApi = api('secure-api', {
  middleware: [authMiddleware],
})

Security

APIs can be secured using OIDC-compatible providers like Auth0, FusionAuth, or AWS Cognito. Security can be applied at the API level or per route:

import { api, oidcRule } from '@nitric/sdk'

const auth0Rule = oidcRule({
  name: 'auth0',
  issuer: 'https://your-tenant.auth0.com',
  audiences: ['your-api-identifier'],
})

const secureApi = api('secure-api', {
  security: [auth0Rule('user.read')],
})

Custom Domains

You can configure custom domains for your APIs in your stack configuration:

provider: nitric/aws@1.1.0
region: us-east-1

apis:
  my-api:
    domains:
      - api.example.com

Custom domains are currently only supported for AWS deployments. See the AWS Custom Domain Setup section for setup details.

Project Organization

Multiple Services

You can split your API routes across multiple services while using the same API resource:

import { api } from '@nitric/sdk'

const myApi = api('my-api')

myApi.get('/users', async (ctx) => {
  // Handle user listing
})

import { api } from '@nitric/sdk'

const myApi = api('my-api')

myApi.get('/products', async (ctx) => {
  // Handle product listing
})

Shared Resources

For better organization, you can define shared API resources:

import { api } from '@nitric/sdk'

export const myApi = api('my-api')

Then import and use them in your services:

import { myApi } from '../resources/api'

myApi.get('/users', async (ctx) => {
  // Handle user listing
})

Cloud Provider Support

Each cloud provider has specific features and limitations for API deployments:

Security rules are not enforced during local development.