> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# registerApiRoute()

La fonction `registerApiRoute()` crée des routes HTTP personnalisées qui s'intègrent au serveur Mastra. Les routes peuvent inclure des métadonnées OpenAPI afin d'apparaître dans la documentation Swagger UI.

## Importation

```typescript
import { registerApiRoute } from '@mastra/core/server'
```

## Paramètres

### path

Chemin URL de la route. Prend en charge les paramètres de chemin au moyen de la syntaxe `:param`.

```typescript
registerApiRoute("/items/:itemId", { ... })
```

Les chemins des routes personnalisées ne peuvent pas commencer par la valeur `apiPrefix` configurée du serveur (par défaut : `/api`), car ce préfixe est réservé aux routes Mastra intégrées. Si vous définissez une valeur `apiPrefix` personnalisée, seul ce préfixe est réservé. Par exemple, avec `apiPrefix: '/mastra/api'`, les chemins tels que `/api/my-endpoint` sont autorisés.

> **Attention:** La configuration d'authentification par défaut protège `/api/*` et considère `/api` et `/api/auth/*` comme publics. Lorsque vous modifiez `apiPrefix`, ces valeurs par défaut ne correspondent plus et les routes intégrées ne sont plus couvertes par le motif protégé. Mettez à jour `server.auth.protected` et `server.auth.public` afin qu'ils référencent le nouveau préfixe, ainsi que tout code client (notamment `MastraClient` et sa valeur `apiPrefix`) qui accède à `/api/*`.

### options

**method** (`'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'`): Méthode HTTP de la route

**handler** (`Handler`): Fonction Handler de la route recevant le Context Hono. Utilisez handler ou createHandler, mais pas les deux.

**createHandler** (`({ mastra }: { mastra: Mastra }) => Promise<ApiRouteHandler>`): Factory asynchrone qui reçoit l'instance Mastra et renvoie le Handler de la route. Elle s'exécute une fois au démarrage du serveur et peut donc effectuer une configuration ponctuelle. Utilisez handler ou createHandler, mais pas les deux.

**middleware** (`MiddlewareHandler | MiddlewareHandler[]`): Fonctions de middleware propres à la route

**cors** (`CorsOptions`): Configuration CORS propre à la route. Utilisez-la lorsqu'une route personnalisée nécessite une politique cross-origin différente de server.cors.

**openapi** (`DescribeRouteOptions`): Métadonnées OpenAPI de la documentation Swagger UI

## Options OpenAPI

La propriété `openapi` accepte les champs d'opération OpenAPI 3.1 standard de [hono-openapi](https://github.com/honojs/middleware/tree/main/packages/openapi). Les routes dépourvues de propriété `openapi` ne sont pas incluses dans Swagger UI.

**summary** (`string`): Résumé succinct de l'opération

**description** (`string`): Description détaillée de l'opération

**tags** (`string[]`): Tags de regroupement dans Swagger UI. Utilise par défaut \['custom'] s'ils ne sont pas indiqués.

**deprecated** (`boolean`): Marque l'opération comme obsolète

**parameters** (`ParameterObject[]`): Paramètres de chemin, de requête et d'en-tête

**requestBody** (`RequestBodyObject`): Spécification du corps de la requête

**responses** (`ResponsesObject`): Spécifications des réponses par code de statut

**security** (`SecurityRequirementObject[]`): Exigences de sécurité de l'opération

## Valeur renvoyée

Renvoie un objet `ApiRoute` à transmettre à `server.apiRoutes` dans la configuration de Mastra.

## Contexte du Handler

Le Handler reçoit un objet Hono `Context` donnant accès aux éléments suivants :

```typescript
handler: async c => {
  // Get the Mastra instance
  const mastra = c.get('mastra')

  // Get request context
  const requestContext = c.get('requestContext')

  // Access path parameters
  const itemId = c.req.param('itemId')

  // Access query parameters
  const filter = c.req.query('filter')

  // Access request body
  const body = await c.req.json()

  // Return JSON response
  return c.json({ data: 'value' })
}
```

## Exemples

### Route GET de base

```typescript
import { Mastra } from '@mastra/core'
import { registerApiRoute } from '@mastra/core/server'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      registerApiRoute('/health-check', {
        method: 'GET',
        handler: async c => {
          return c.json({ status: 'ok' })
        },
      }),
    ],
  },
})
```

### Route avec paramètres de chemin

```typescript
registerApiRoute('/users/:userId/posts/:postId', {
  method: 'GET',
  handler: async c => {
    const userId = c.req.param('userId')
    const postId = c.req.param('postId')

    return c.json({ userId, postId })
  },
})
```

### Route POST avec corps

```typescript
registerApiRoute('/items', {
  method: 'POST',
  handler: async c => {
    const body = await c.req.json()
    const mastra = c.get('mastra')

    // Process the request...

    return c.json({ id: 'new-id', ...body }, 201)
  },
})
```

### Route avec middleware

```typescript
registerApiRoute('/protected', {
  method: 'GET',
  middleware: [
    async (c, next) => {
      const token = c.req.header('Authorization')
      if (!token) {
        return c.json({ error: 'Unauthorized' }, 401)
      }
      await next()
    },
  ],
  handler: async c => {
    return c.json({ data: 'protected content' })
  },
})
```

### Route avec CORS

Utilisez une configuration CORS propre à la route lorsqu'une route personnalisée nécessite des identifiants cross-origin, tandis que le reste du serveur doit conserver la politique CORS globale.

```typescript
registerApiRoute('/customer-webhook', {
  method: 'POST',
  cors: {
    origin: ['https://customer-saas.example'],
    credentials: true,
  },
  handler: async c => {
    return c.json({ ok: true })
  },
})
```

### Route avec documentation OpenAPI

```typescript
import { z } from 'zod'

const ItemSchema = z.object({
  id: z.string(),
  name: z.string(),
  price: z.number(),
})

registerApiRoute('/items/:itemId', {
  method: 'GET',
  openapi: {
    summary: 'Get item by ID',
    description: 'Retrieves a single item by its unique identifier',
    tags: ['Items'],
    parameters: [
      {
        name: 'itemId',
        in: 'path',
        required: true,
        description: 'The item ID',
        schema: { type: 'string' },
      },
    ],
    responses: {
      200: {
        description: 'Item found',
        content: {
          'application/json': {
            schema: ItemSchema, // Zod schemas are converted to JSON Schema during OpenAPI generation
          },
        },
      },
      404: {
        description: 'Item not found',
      },
    },
  },
  handler: async c => {
    const itemId = c.req.param('itemId')
    return c.json({ id: itemId, name: 'Example', price: 9.99 })
  },
})
```

### Utilisation de `createHandler()`

Pour les routes nécessitant une initialisation asynchrone :

```typescript
registerApiRoute('/dynamic', {
  method: 'GET',
  createHandler: async ({ mastra }) => {
    // Perform one-time async setup
    const config = await loadConfig()
    const agent = mastra.getAgent('weatherAgent')

    return async c => {
      return c.json({ config, agent: agent.name })
    }
  },
})
```

## Gestion des erreurs

Levez des erreurs accompagnées de codes de statut au moyen de `HTTPException` de Hono :

```typescript
import { HTTPException } from 'hono/http-exception'

registerApiRoute('/items/:itemId', {
  method: 'GET',
  handler: async c => {
    const itemId = c.req.param('itemId')
    const item = await findItem(itemId)

    if (!item) {
      throw new HTTPException(404, { message: 'Item not found' })
    }

    return c.json(item)
  },
})
```

## Voir aussi

- [Guide des routes API personnalisées](https://mastra.zisheng.pro/fr/docs/server/custom-api-routes) : guide d'utilisation avec des exemples
- [Middleware du serveur](https://mastra.zisheng.pro/fr/docs/server/middleware) : configuration globale du middleware
- [createRoute()](https://mastra.zisheng.pro/fr/reference/server/create-route) : création de routes avec typage sûr pour les adaptateurs de serveur
- [Routes du serveur](https://mastra.zisheng.pro/fr/reference/server/routes) : routes intégrées du serveur Mastra