API proxy rewrite

Proxy an external API through your domain using vercel.ts. Requests to /api/external/:path* are rewritten to your backend, cached at the CDN, and tagged for targeted purging.

Proxying puts the Vercel CDN in front of your backend, improving performance through Vercel's global edge network and reducing cost with built-in caching. It also adds a layer of security with the Vercel Firewall.

Demo

https://proxy-requests-to-external-origins.vercel.app/

Visit /blog to see blog posts fetched from an external API through the CDN proxy.

How to use

One-Click Deploy

Deploy the template on Vercel using this link.

To proxy your own API instead of the demo, set the EXTERNAL_API_URL environment variable in your project settings or update the default value in vercel.ts, then redeploy. By default, the template uses jsonplaceholder.typicode.com as the external API.

Clone and Deploy

1
pnpm create next-app --example https://github.com/vercel/examples/tree/main/cdn/api-proxy-rewrite
2
cd api-proxy-rewrite
3
pnpm install
4
pnpm dev

How it works

The rewrite and caching configuration lives in vercel.ts:

1
import { routes, type VercelConfig } from '@vercel/config/v1'
2

3
const EXTERNAL_API_URL =
4
  process.env.EXTERNAL_API_URL || 'https://jsonplaceholder.typicode.com'
5

6
export const config: VercelConfig = {
7
  framework: 'nextjs',
8
  outputDirectory: '.next',
9
  rewrites: [
10
    routes.rewrite('/api/external/:path*', `${EXTERNAL_API_URL}/:path*`),
11
  ],
12
  headers: [
13
    routes.header('/api/external/:path*', [
14
      {
15
        key: 'CDN-Cache-Control',
16
        value: 'public, max-age=60, stale-while-revalidate=3600',
17
      },
18
      { key: 'Vercel-Cache-Tag', value: 'api' },
19
    ]),
20
  ],
21
}

1. The Next.js app renders the blog page and fetches /api/external/posts
2. The rewrite in vercel.ts matches /api/external/:path* and proxies the request to your configured backend
3. The CDN-Cache-Control header caches responses at the edge for 1 minute, with a 1-hour stale-while-revalidate window
4. The Vercel-Cache-Tag header tags responses with api for targeted cache purging

CDN caching

CDN-Cache-Control controls caching at the Vercel CDN only. Unlike Cache-Control, which affects both the browser and CDN, CDN-Cache-Control is stripped before reaching the browser.

• max-age=60: The CDN serves cached responses for 1 minute without hitting the external API.
• stale-while-revalidate=3600: After the 1-minute window, the CDN serves stale content immediately while fetching a fresh copy in the background.

Cache tags

Vercel-Cache-Tag: api labels cached responses with a tag. You can purge all responses tagged api without flushing the entire project cache:

• Dashboard: Navigate to CDN > Caches, select Cache Tag, enter api, and click Purge
• CLI:

1
vercel cache invalidate --tag api

No-code alternative

If you prefer to configure routing without code or redeployment, you can use project level routing rules through the Vercel Dashboard, CLI, API, or SDK. See the Add API External Rewrite Routing Rule template for a no-code approach.