Begrip: protectedApiRoute & publicApiRoute

De protectedApiRoute en publicApiRoute functies, die aangeboden wordt door de backend-docenten, zijn functies die alle gemeenschappelijke logica voor een API route afzonderen.

Deze functies controleren de ingestuurde data met een Zod schema, geven eventuele foutmeldingen terug, voeren een opgegeven functie met backend code uit en logt dit proces. Voor de protected variant wordt ook gecontroleerd of de gebruiker ingelogd is en eventueel of deze de juiste rol heeft. Deze controle kan zowel stateful als stateless uitgevoerd worden, via een secure HTTP-only session cookie of via een bearer token in de authentication header.

De apiRoute functies hebben één parameter object met volgende properties:

• schema: Een Zod schema dat de invoer valideert (uit het request body of de query parameters)
• routeFn: Een functie die een void, NextResponse teruggeeft (al dan niet in een Promise) en backend-code uitvoert. routeFn heeft twee parameter objecten met volgende properties:
  • Parameter 1: Context
    • data: De gevalideerde data.
    • profile: Het profiel van de huidige gebruiker. Enkel beschikbaar in de protectedApiRoute variant.
    • logger: Een instantie van de Pino logger met requestId, userId, ...
  • Parameter 2: Route parameters
    • Een object met de parameters die gedefinieerd worden als onderdeel van het pad in de URL.
• type: Een optionele parameter die de databron aanduidt, er zijn drie mogelijke opties:
  • body: Data wordt ingestuurd als een JSON-object in de body van een POST, PUT of PATCH request. Dit is de defaultwaarde.
  • form: Data wordt ingestuurd als een form encoded data in de body van een POST, PUT of PATCH request.
  • searchParams: Data wordt ingestuurd als searchparameters in de URL van het request.
• authenticationType: Een optionele parameter die aangeeft hoe de gebruiker geauthenticeerd moet worden, de mogelijke opties zijn:
  • jwt: Gebruik een JWT token die doorgegeven wordt als een bearer token in de authentication header. Dit is de defaultwaarde.
  • cookie: Gebruik een secure HTTP-only session cookie met een JWT token als value.
• requiredRoles: Een optionele array van de gebruikers rollen die toegang hebben tot de functie. Als de array niet meegegeven wordt, heeft elke gebruiker toegang. Enkel beschikbaar in de protectedFormAction variant.

// Een API route waarvoor de gebruiker INGELOGD moet zijn (via een JWT in de headers).
export const GET = protectedApiRoute({
  routeFn: async ({data, profile, logger}) => {
    // Database operaties en andere backend logica.
  },
}

// Een API route waarvoor de gebruiker INGELOGD moet zijn (via een session cookie).
export const GET = protectedApiRoute({
  routeFn: async ({data, profile, logger}) => {
    // Database operaties en andere backend logica.
  },
  authenticationType: 'cookie',
}

// Een action waarvoor de gebruiker INGELOGD moet zijn (via een JWT in de headers) en de Admin rol moet hebben.
// Daarnaast moet er data ingestuurd worden via een JSON object in de body van het request en moet er een route parameter
// meegegeven worden.  
export const PUT = protectedApiRoute({
  schema: zodSchema,
  routeFn: async ({data, profile, logger}, {fooId}: {fooId: string}) => {
    // Database operaties en andere backend logica.
  },
  requiredRoles: [Role.Admin],
}

// Een action waarvoor de gebruiker NIET ingelogd moet zijn.
export const GET = = publicApiRoute({
  routeFn: async ({data, logger}) => {
    // Database operaties en andere backend logica.
  },
}