Building an API

Learn how to build RESTful APIs with Remix using fetch-router and controllers

1. Set up your router

   First, create a router with middleware. The router handles all HTTP requests and applies middleware in order.

   app/router.ts

   import { createRouter } from 'remix/fetch-router'
   import { logger } from 'remix/logger-middleware'
   import { compression } from 'remix/compression-middleware'
   
   let middleware = []
   
   if (process.env.NODE_ENV === 'development') {
     middleware.push(logger())
   }
   
   middleware.push(compression())
   
   export let router = createRouter({ middleware })
   

   The createRouter function creates a router instance that you can map routes to. Middleware runs for every request before your route handlers.

2. Define your routes

   Create a type-safe routes definition using the routes helper. This provides autocomplete and type checking.

   app/routes.ts

   import { routes } from 'remix/fetch-router/routes'
   
   export let apiRoutes = routes({
     users: {
       index: 'GET /api/users',
       show: 'GET /api/users/:id',
       create: 'POST /api/users',
       update: 'PATCH /api/users/:id',
       delete: 'DELETE /api/users/:id',
     },
     posts: {
       index: 'GET /api/posts',
       show: 'GET /api/posts/:id',
       create: 'POST /api/posts',
     },
   })
   

   Each route maps to an HTTP method and path pattern. Path parameters like :id are automatically extracted and typed.

3. Create a controller

   Controllers group related route handlers together. Each action receives a request context with typed params.

   app/users.ts

   import type { Controller } from 'remix/fetch-router'
   import { apiRoutes } from './routes.ts'
   
   // Sample in-memory database
   let users = [
     { id: 1, name: 'Alice', email: '[e-mail]' },
     { id: 2, name: 'Bob', email: '[e-mail]' },
   ]
   
   export default {
     actions: {
       // GET /api/users - List all users
       index() {
         return Response.json(users)
       },
   
       // GET /api/users/:id - Get a single user
       show({ params }) {
         let user = users.find(u => u.id === Number(params.id))
         
         if (!user) {
           return Response.json(
             { error: 'User not found' },
             { status: 404 }
           )
         }
   
         return Response.json(user)
       },
   
       // POST /api/users - Create a new user
       async create({ request }) {
         let body = await request.json()
         
         let newUser = {
           id: users.length + 1,
           name: body.name,
           email: body.email,
         }
   
         users.push(newUser)
   
         return Response.json(newUser, { status: 201 })
       },
   
       // PATCH /api/users/:id - Update a user
       async update({ params, request }) {
         let user = users.find(u => u.id === Number(params.id))
         
         if (!user) {
           return Response.json(
             { error: 'User not found' },
             { status: 404 }
           )
         }
   
         let body = await request.json()
         Object.assign(user, body)
   
         return Response.json(user)
       },
   
       // DELETE /api/users/:id - Delete a user
       delete({ params }) {
         let index = users.findIndex(u => u.id === Number(params.id))
         
         if (index === -1) {
           return Response.json(
             { error: 'User not found' },
             { status: 404 }
           )
         }
   
         users.splice(index, 1)
         return new Response(null, { status: 204 })
       },
     },
   } satisfies Controller<typeof apiRoutes.users>
   

   The satisfies operator ensures your controller matches the routes structure, providing full type safety.

4. Map controllers to routes

   Connect your controller to the router using the map method:

   app/router.ts

   import { createRouter } from 'remix/fetch-router'
   import { apiRoutes } from './routes.ts'
   import usersController from './users.ts'
   import postsController from './posts.ts'
   
   export let router = createRouter()
   
   // Map the entire users controller
   router.map(apiRoutes.users, usersController)
   
   // Map the entire posts controller
   router.map(apiRoutes.posts, postsController)
   

   You can also map individual routes:

   router.get(apiRoutes.users.index, async () => {
     return Response.json({ users: [] })
   })
   
5. Add request validation

   Use middleware to validate requests before they reach your handlers:

   app/middleware/validate.ts

   import type { Middleware } from 'remix/fetch-router'
   
   export function validateJson(): Middleware {
     return async ({ request }, next) => {
       let contentType = request.headers.get('content-type')
       
       if (request.method !== 'GET' && !contentType?.includes('application/json')) {
         return Response.json(
           { error: 'Content-Type must be application/json' },
           { status: 415 }
         )
       }
   
       return next()
     }
   }
   

   Apply it to specific controllers:

   app/users.ts

   import { validateJson } from './middleware/validate.ts'
   
   export default {
     middleware: [validateJson()],
     actions: {
       // ... your actions
     },
   } satisfies Controller<typeof apiRoutes.users>
   
6. Handle errors

   Add error handling middleware to catch and format errors:

   app/middleware/errors.ts

   import type { Middleware } from 'remix/fetch-router'
   
   export function errorHandler(): Middleware {
     return async (context, next) => {
       try {
         return await next()
       } catch (error) {
         console.error('Request error:', error)
         
         return Response.json(
           {
             error: 'Internal server error',
             message: error instanceof Error ? error.message : 'Unknown error',
           },
           { status: 500 }
         )
       }
     }
   }
   

   Add it as the first middleware:

   app/router.ts

   import { errorHandler } from './middleware/errors.ts'
   
   let middleware = [
     errorHandler(),
     logger(),
     compression(),
   ]
   
   export let router = createRouter({ middleware })
   
7. Start your server

   Create a server to handle requests:

   server.ts

   import { createServer } from 'remix/node-fetch-server'
   import { router } from './app/router.ts'
   
   let server = createServer(router)
   
   let port = process.env.PORT || 3000
   server.listen(port, () => {
     console.log(`API server running on http://localhost:${port}`)
   })
   
   // Clean shutdown
   process.on('SIGINT', () => {
     server.close(() => process.exit(0))
   })
   process.on('SIGTERM', () => {
     server.close(() => process.exit(0))
   })
   

API Best Practices

Use proper HTTP status codes

• 200 OK - Successful GET, PATCH, PUT
• 201 Created - Successful POST that creates a resource
• 204 No Content - Successful DELETE
• 400 Bad Request - Invalid request data
• 404 Not Found - Resource doesn’t exist
• 500 Internal Server Error - Server error

Return consistent error formats

interface ApiError {
  error: string
  message?: string
  field?: string
}

return Response.json(
  { error: 'Validation failed', field: 'email', message: 'Invalid email format' },
  { status: 400 }
)

Version your API

export let apiRoutes = routes({
  v1: {
    users: {
      index: 'GET /api/v1/users',
      show: 'GET /api/v1/users/:id',
    },
  },
})

Related Documentation

• fetch-router API Reference
• Middleware Guide
• Request Context