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

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.

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. 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 :

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

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

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

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

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.

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

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 :

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 :

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 : guide d'utilisation avec des exemples
• Middleware du serveur : configuration globale du middleware
• createRoute() : création de routes avec typage sûr pour les adaptateurs de serveur
• Routes du serveur : routes intégrées du serveur Mastra