> For the complete documentation index, see [llms.txt](https://docs.novel.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.novel.dev/novel-server/routing.md).

# Routing

## File-based Routing

The APIs are located in your `/app/api`directory.

It autoloads all the files that live in this directory if it follows the format below.

{% code title="app/api/accounts/index.ts" lineNumbers="true" %}

```typescript
export default async function Route (instance: FastifyInstance) {
    instance.get('/api/v1/account', handler);
    
    async function handler(request, reply) {
        console.log(request);
        reply.status(204);
    }
}
```

{% endcode %}

This file is automatically loaded when novel starts. 

It still needs you to specify the endpoint of the API via [Fastify's routing](https://fastify.dev/docs/latest/Reference/Routes/).

> `instance`is an instance of a Fastify plugin. All Fastify interfaces are available here and additional ones that are discussed below.

Below are all the examples of valid route registrations

{% code lineNumbers="true" %}

```typescript
instance.get('/api/v1/account', handler);
instance.post('/api/v1/account', handler);
instance.patch('/api/v1/account', handler);
instance.head('/api/v1/account', handler);
instance.put('/api/v1/account', handler);
instance.delete('/api/v1/account', handler);
instance.options('/api/v1/account', handler);
instance.any('/api/v1/account', handler);

// you can add fastify route options as well
instance.get('/api/v1/account', fastifyRouteOptions, handler);
```

{% endcode %}

The routes are attached in their own scope 

{% embed url="<https://docs.novel.dev/guides/knowledge-base/novel-server/creating-a-rest-endpoint>" %}

## Built-in Routes

Novel comes with plenty of built-in routes that are created to glue together various SaaS functionalities.

These routes are available under `/app/api/internal/v1`and exposed under `/api/v1`.&#x20;

You can inspect these routes using the API reference in this documentation, or the files in the Novel API repository

[See API Reference →](/novel-server/novel-api/api-reference.md)

See <https://github.com/madewithnovel/novel/tree/main/app/api/internal/v1>

## Protecting Routes

You can secure your endpoints by making use of the various ways Novel scopes requests. There are 2 standard modes: `cookie` and `api keys`.

{% embed url="<https://docs.novel.dev/guides/knowledge-base/novel-server/securing-an-endpoint>" %}

The functions below are called [Route Directives](/novel-server/routing/route-directives.md). Check other route directives available to you.

## Cookie

The cookie session allows all requests into the Novel API with the `session`cookie to be acknowledged and keep a session related to a user.

### `instance.authenticated()`

You can access this session via the request variable in your handler.

{% code title="app/api/accounts/index.ts" lineNumbers="true" %}

```typescript
export default async function Route (instance: FastifyInstance) {
    instance.get('/api/v1/account', handler);
    instance.authenticated();
    
    async function handler(request, reply) {
        console.log(request.session);
        reply.status(204);
    }
}
```

{% endcode %}

{% hint style="info" %}
These sessions are the same in both cookie and api key contexts.
{% endhint %}

There are also additional request variables available to you for convenience.

#### `request.account`&#x20;

This includes details on which user is accessing that request.

```typescript
request.account = {
    id: string,
    role: string,
    verified: boolean,
};
```

#### `request.org`

This includes details on which organization is being used by the current request

```typescript
request.org = {
    id: string,
}
```

{% embed url="<https://docs.novel.dev/novel-server/sessions>" %}

## Request  Context

Each route has access to a request context that uses Node's `async_hooks`, and `@fastify/request-context` library.

This allows Novel to tap into relevant context of the request outside of the request handler. For example, retrieving an account ID in a database model.

## Using API Keys

If you want to restrict endpoints based on API keys, you can use the directive below:

### `instance.authorized()`

{% code title="app/api/accounts/index.ts" lineNumbers="true" %}

```typescript
export default async function Route (instance: FastifyInstance) {
    instance.get('/api/v1/account', handler);
    instance.authorized();
    
    async function handler(request, reply) {
        console.log(request.session);
        reply.status(204);
    }
}
```

{% endcode %}

{% hint style="info" %}
These sessions are the same in both cookie and api key contexts.
{% endhint %}

This will check if the API key belongs to a specific user and fill in the relevant session variables like the above.

{% hint style="info" %}
You can use both `authorized` and `authenticated` directives in the same route definition.
{% endhint %}

## Changelog

* 2024-12-20 - Initial Documentation