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

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:

• AWS
• Azure
• Google Cloud