> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: HTTP Endpoint Extension Files and Code

## Article: HTTP Endpoint Extension Files and Code

## Article Link: https://dev.wix.com/docs/backend-extensions/http-endpoints/http-endpoint-extension-files-and-code.md

## Article Content:

# HTTP Endpoint Extension Files and Code

An [HTTP endpoint](https://dev.wix.com/docs/overview/extensions-framework/backend-extensions/http-endpoints.md) is a single TypeScript file that exports a handler for each HTTP method it supports. Wix finds the file from its location, so the file's path sets the route.

Unlike other extension types, an HTTP endpoint has no configuration file. It isn't registered in `extensions.ts`, and it doesn't appear in a list of extensions.

## File location

The folder, the route prefix, and the handler type's package depend on the project. The following table shows where an endpoint named `orders` goes:

| Project | File | Route | `APIRoute` import |
| --- | --- | --- | --- |
| Studio Two site | `src/api/orders.ts` | `orders` | `@wix/custom-extensions/types` |
| Wix CLI app or Wix-managed headless project | `src/pages/api/orders.ts` | `api/orders` | `astro` |

The route is the path that follows the base URL your endpoints are served from.

### Change the folder in a Studio Two site

To serve endpoints from a different folder, set `apiDir` on `app()` in `src/extensions.ts`. The path is relative to `src/`:

```ts
import { app } from '@wix/custom-extensions';

export default app({ apiDir: './server-routes' });
```

The folder you set replaces `src/api/`. Wix doesn't serve endpoints from `src/api/` when `apiDir` points elsewhere.

## Routes in a Studio Two site

Every `.ts` or `.js` file in the endpoints folder, except `.d.ts` files, becomes a route, including a file that holds only shared helper code.

The route is the file's path in the folder, without the file extension. A file named `index.ts` serves the route of its folder. The following table shows how file paths map to routes:

| File | Route |
| --- | --- |
| `src/api/reviews.ts` | `reviews` |
| `src/api/reviews/index.ts` | `reviews` |
| `src/api/reviews/summary.ts` | `reviews/summary` |
| `src/api/reviews/[reviewId].ts` | `reviews/<any value>`, such as `reviews/abc-123` |
| `src/api/catalog/[...slug].ts` | `catalog/<one or more segments>`, such as `catalog/shoes/red` |

A segment in square brackets is dynamic. The handler reads its value from [`params`](#handler-context), using the name inside the brackets. For example, a request to `reviews/abc-123`, handled by `[reviewId].ts`, has `params.reviewId` set to `abc-123`. A rest segment, such as `[...slug]`, captures the rest of the path, so `catalog/shoes/red` sets `params.slug` to `shoes/red`.

Route rules:

- Each route can belong to only one file. For example, `src/api/reviews.ts` and `src/api/reviews/index.ts` can't both exist. If two files resolve to the same route, the build fails.
- Routes that start with `_wix` are reserved for Wix. A file that resolves to one fails the build.

## Routes in a Wix CLI app or Wix-managed headless project

A Wix CLI app and a headless project use Astro's file-based routing, so an endpoint file in `src/pages/api/` follows [Astro's routing rules](https://docs.astro.build/en/guides/routing/), including dynamic and rest segments in square brackets. The route always starts with `api/`.

In a headless project, the Astro integration registers some routes of its own, such as `/api/auth/login`. Don't add an endpoint at one of those paths. For the full list, see [Reserved URL Paths for the Astro Integration](https://dev.wix.com/docs/go-headless/wix-managed-headless/full-integration-astro/development/reserved-url-paths-for-the-astro-integration.md).

## Handler

Each handler is an exported constant named for the HTTP method it handles, such as `GET`, `POST`, `PUT`, or `DELETE`, and typed as `APIRoute`. A handler receives a [context object](#handler-context) and returns a standard [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), or a promise that resolves to one.

Import `APIRoute` from the package your project uses:

```ts
// Studio Two site
import type { APIRoute } from '@wix/custom-extensions/types';
```

```ts
// Wix CLI app or headless project
import type { APIRoute } from 'astro';
```

A generated endpoint file exports a `GET` handler that returns a JSON message and a `POST` handler that returns the JSON body it receives:

```ts
export const GET: APIRoute = async () => {
  return new Response(
    JSON.stringify({ message: 'Hello from /orders' }),
    { headers: { 'Content-Type': 'application/json' } }
  );
};

export const POST: APIRoute = async ({ request }) => {
  const data = await request.json();

  return new Response(JSON.stringify(data), {
    headers: { 'Content-Type': 'application/json' },
  });
};
```

### Handler context

The context object includes these properties in every project:

| Property | Type | Description |
| --- | --- | --- |
| `request` | [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) | The incoming request. Read a JSON body with `await request.json()`, and headers with `request.headers`. |
| `url` | [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) | The request URL. Read query parameters with `url.searchParams`. |
| `params` | object | The values of the route's dynamic segments, keyed by the names inside the square brackets. |

In a Wix CLI app or a headless project, the context is Astro's [`APIContext`](https://docs.astro.build/en/reference/api-reference/), which has more properties, such as `cookies` and `redirect()`.

### Responses and errors in a Studio Two site

A handler sets its own status codes. Wix returns these responses without running your handler, or in place of its response:

| Status | When |
| --- | --- |
| `401` | The request has no access token. |
| `404` | No file serves the route. The body is empty. |
| `500` | The handler throws an error that it doesn't catch. The body is `Internal Server Error`, and the error message stays on the server. |

## See also

- [About HTTP Endpoints](https://dev.wix.com/docs/backend-extensions/http-endpoints/about-http-endpoints.md)
- [HTTP Endpoints](https://dev.wix.com/docs/overview/extensions-framework/backend-extensions/http-endpoints.md)