---
title: API Server
slug: oip-next/8e0L-api-server
icon: {"lucideIcon":"📘"}
createdAt: 2025-11-03T11:15:57.000Z
---

# Présentation

L'API server expose les éléments suivants (*named exports*) :

- la méthode `start` qui permet d'initialiser l'application *Express* ;
- la méthode `getPubSub` qui permet de récupérer l'instance *PubSub* pour la gestion des *subscriptions* graphQL ;
- les utilitaires des resolvers graphQL `OK` et `KO` ;
- la méthode `handleTask` nécessaire à l'éxecution des tâches ;
- l'utilitaire `getEnv` qui permet de résoudre la valeur d'une variable d'environnement ;
- l'utilitaire `validateResolverContext` qui permet de valider le contexte d'appel d'un resolver d'une vue.

Les imports depuis l'OAV :

```javascript
import {
  start,
  getPubSub,
  OK,
  KO,
  handleTask,
  getEnv,
  validateResolverContext,
} from '@fasstech/oip-starter-utils/server';
```

# Méthode start

La méthode `start` initialise l'application *Express* de l'OAV. Elle prend en paramètre un objet de configuration. La méthode retourne l'application *Express&#x20;*`app`

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  // options
};

const { app } = await start(serverCfg);

// init your business logic here
void app;
```
:::

## Propriétés requises

### graphql

Initialise le schéma graphQL de l'OAV et permet la configuration de seuils de sécurité du server graphQL.

**graphql.resolvers**

La liste des resolvers graphQL de l'OAV est attendue en valeur.

**graphql.typeDefs**

La liste des définitions des types graphQL de l'OAV est attendue en valeur.

**graphql.security**

:::BlockQuote
**\[info]** Propriété optionnelle
:::

Cette propriété accepte les sous-propriétés optionnelles suivantes :

- `payloadLimit` => permet de définir la taille maximale autorisée de la payload des requêtes graphQL entrantes. Par défaut, la limite est définie sur *50kb*
- `maxCoercionErrors` => permet de configurer le nombre maximal d'erreurs de coercition de variables (*variable coercion errors*) qu'Apollo Server acceptera avant de rejeter une requête avec un code d'état 400. Limite définie à `50` par défaut.
- `maxErrors` => permet de limiter le nombre maximal d'erreurs de validation GraphQL accumulées avant qu'Apollo Server n'arrête le processus de validation et ne rejette la requête. Limite définie à `10` par défaut.
- `armorConfig` => permet de configurer les valeurs des seuils de sécurité gérés par la lib [graphql-armor](https://escape.tech/graphql-armor/docs/category/plugins/). Les règles de validation suivantes sont configurables :
  - [field suggestions](https://escape.tech/graphql-armor/docs/plugins/block-field-suggestions/)
  - [cost limit](https://escape.tech/graphql-armor/docs/plugins/cost-limit/)
  - [max aliases](https://escape.tech/graphql-armor/docs/plugins/max-aliases/)
  - [max depth](https://escape.tech/graphql-armor/docs/plugins/max-depth/)
  - [max directives](https://escape.tech/graphql-armor/docs/plugins/max-directives/)
  - [max tokens](https://escape.tech/graphql-armor/docs/plugins/max-tokens/)

Par défaut, les valeurs par défaut de la lib *graphql-armor* sont utilisées pour la configuration de la propriété `graphql.security.armorConfig`

Se référer à la documentation de la lib [graphql-armor](https://escape.tech/graphql-armor/docs/category/plugins/) pour connaitre le type attendu des objets de configuration acceptés et leurs valeurs par défaut.

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  graphql: {
    resolvers: [/* ...resolvers */],
    typeDefs: [/* ...typeDefs */],
    security: {
      payloadLimit: '1kb',
      armorConfig: {
        maxDepth: {
          n: 3,
        },
        costLimit: {
          maxCost: 20,
        },
        maxTokens: {
          n: 100,
        },
      },
    },
  },
  // ...
};

const { app } = await start(serverCfg);

// init your business logic here
void app;
```
:::

### process

Permet la configuration de l'objet *Process*.

**process.resolveFirstView**

La callback de la résolution conditionnelle de la première vue du parcours est attendue en valeur.

Signature : \*(\{ **projectId**: string; **viewId?**: string; **metadata?**: object }) => \****Promise\<string>***

Cette callback a pour but de résoudre l'id de la première vue du parcours. Le corps de la fonction doit impérativement retourner l'id d'une vue. La callback reçoit en paramètre l'id de l'entité *Project* actuelle `projectId`. Si l'entité *Project* est liée à une session précédente, la callback reçoit également `viewId` qui identifie la dernière vue active du parcours ainsi que ses metadonnées `metadata` si elles existent.

**process.extendWith**

:::BlockQuote
**\[info]** Propriété optionnelle
:::

La callback qui permet de résoudre les propriétés personnalisées de l'objet *Process* est attendue en valeur. Elle reçoit en paramètre l'objet *Process.*

Signature : \*(**process**: Process) => \****Promise\<ExtendedProcess>***

L'objet qui représente le *Process&#x20;*&#xE9;tendu doit être résolu et retourné. Le type de l'objet doit correspondre au type graphQL *ExtendedProcess&#x20;*&#x64;éfinit dans le code de l'OAV.

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start } from '@fasstech/oip-starter-utils/server';
import { resolveFirstView } from './resolve-first-view.mjs'
import { extendWith } from './extend-with.mjs'

const serverCfg = {
  process: {
    resolveFirstView,
    extendWith,
  },
  // ...
};

const { app } = await start(serverCfg);

// init your business logic here
void app;
```

resolve-first-view\.mjs

```javascript
export const resolveFirstView = async ({ projectId, viewId, metadata }) => {
  // pour gérer la reprise du parcours
  if (viewId) {
    return viewId; // ou autre viewId
  }

  // récupération de l'entité Project
  const project = await $Project(projectId);

  // votre logique

  return 'my-desired-view-id';
};
```

extend-with.mjs

```javascript
export const extendWith = async (process) => {
  const customField = await someLogic();
  
  return {
    ...process,
    customField
  };
}; 
```
:::

### session

Permet de configurer la résolution du contexte client et de l'entité Project relative lors du décrochage.

**session.validateProjectId**

Cette callback permet de vérifier la validité de `projectId` lors d'un décrochage avec le paramètre *projectId* au lieu de *token.*

Signature : (\{ **projectId**: string; **sessionId?**: string; clientId?: string }) => **Promise\<boolean>**

Elle reçoit en paramètre `projectId` et `sessionId`. Le corps de la fonction doit retourner un boolean, *true* si `projectId` est valide, *false* le cas contraire.

À partir de la version **4.3.0** de la bibliothèque, l'identifiant unique de la connexion client `clientId` est également reçu en paramètre.

**session.resolveProjectFromContext**

Cette callback permet de résoudre l'id de l'entité Project `projectId` lors du décrochage sur l'OAV à partir du contexte client.

Signature : *(\{&#x20;*\***...context**\*\*, **sessionId**: string, **clientId**: string }) => \****Promise\<string>***

- Dans un environnement de production ou en mode développement avec la variable `SECURE_SESSION` définie à *true*, la callback reçoit en paramètre un objet qui représente le contexte client résolu ainsi que la propriété `sessionId`.&#x20;
- En mode développement avec la variable `SECURE_SESSION` définie à *false*, la callback reçoit uniquement la propriété `sessionId`. Vous pouvez alors définir et consommer un *mock* du contexte client dans le corps de la fonction pour résoudre l'id de l'entité Project.

Le corps de la fonction doit retourner l'id de l'entité Project relative au contexte client dans tous les cas.

À partir de la version **4.3.0** de la bibliothèque, l'identifiant unique de la connexion client `clientId` est également reçu en paramètre.

**session.resolveContext**

:::BlockQuote
**\[info]** Propriété optionnelle
:::

Si définie, cette callback permet de définir la callback de résolution du contexte client à partir du token lors du décrochage sur l'OAV.

Par défaut, la lib résout le contexte client grâce à un appel au service *Fasst Sessions* ou équivalent avec le token passé en paramètre. L'URL du service est résolu grâce à la variable d'environnement `SESSIONS_SERVICE_URL`

Si vous souhaitez implémenter votre logique personnalisée de résolution du contexte client à partir du token de décrochage, vous devez utiliser la propriété `session.resolveContext` pour définir la callback de résolution du contexte client.

Signature : \*(**token**: string) => \****Promise\<object>***

La callback reçoit en paramètre le *token* de décrochage et doit impérativement retournée un objet représentant le contexte client résolu.

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  session: {
    validateProjectId,
    resolveProjectFromContext,
    resolveContext,
  },
  // ...
};

const { app } = await start(serverCfg);

// init your business logic here
void app;
```

validate-project-id.mjs

```javascript
export const validateProjectId = async ({ projectId }) => {
  // check if projectId is a valid UUID
  const isValid = await isValidUUID(projectId);

  return isValid;
}
```

resolve-project-from-context.mjs

```javascript
export const resolveProjectFromContext = async (context) => {
  // my logic
  
  // find or create new Project entity solved from context

  return projectId;
}
```

resolve-context.mjs

```javascript
export const resolveContext = async (token) => {
  // resolve context client from token
  const context = await resolveContext(token);

  return context;
}
```
:::

**session.resolveMetadata**

:::BlockQuote
**\[info]** Disponible à partir de la version **4.1.0** de la bibliothèque **@fasstech/oip-starter-utils**.
:::

:::BlockQuote
**\[info]** Propriété optionnelle.
:::

Si définie, cette fonction de rappel permet de résoudre les métadonnées qui seront injectées dans l'objet *session* (gérer par la dépendance *express-session*) pour le projet en cours.

Signature : async (**\{ projectId: string, sessionId: string, clientId: string }**) => **Promise\<object>**

La fonction de rappel reçoit en paramètre un objet qui contient `projectId` et `sessionId` et doit retourner un objet qui représente les métadonnées de la session.

À partir de la version **4.3.0** de la bibliothèque, l'identifiant unique de la connexion client `clientId` est également reçu en paramètre.

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start } from '@fasstech/oip-starter-utils/server';
import { resolveMetadata } from './resolve-metadata.mjs';

const serverCfg = {
  session: {
    // ...
    resolveMetadata,
  },
  // ...
};

const { app } = await start(serverCfg);

// init your business logic here
void app;
```

resolve-metadata.mjs

```javascript
export const resolveMetadata = async ({ projectId, sessionId }) => {
  // resolve some data here

  const metadata = {
    something: 42
  };
  
  return metadata;
}
```
:::

**session.clientSync.enabled**

:::BlockQuote
**\[info]** Disponible à partir de la version **4.1.0** de la bibliothèque **@fasstech/oip-starter-utils**.
:::

:::BlockQuote
**\[info]** Propriété optionnelle.
:::

Type *boolean*, `false` par défaut.&#x20;

Permet d'activer la fonctionnalité de la **synchronisation des connexions clientes**. Si activée, le serveur instancie un serveur *WebSocket* qui garantie le contrôle d'un projet (identifié par `projectId`) par un seul client à la fois.

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start } from "@fasstech/oip-starter-utils/server";

let serverConfig = {
  session: {
    // ...
    clientSync: { enabled: true }
  }
};

const { app } = await start(serverConfig);

// init your business logic here
void app;
```
:::

### logger

L'instance d'un *logger* est attendu en valeur.

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { logger } from '@fasstech/logger';
import { start } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  logger,
  // ...
};

const { app } = await start(serverCfg);

// init your business logic here
void app;
```
:::

## Propriétés optionnelles

### basePath

:::BlockQuote
**\[info]** Disponible à partir de la version **4.1.0** de la bibliothèque **@fasstech/oip-starter-utils**.
:::

Une chaîne de caractères qui définit le préfixe des URLs exposées par le serveur :

- `/u/token`
- `/session`
- `/ws-config`
- `/graphql`

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  // ...
  basePath: '/api'
};

// /u/token    -> /api/u/token
// /session    -> /api/session
// /ws-config  -> /api/ws-config
// /graphql    -> /api/graphql

const { app } = await start(serverCfg);

// init your business logic here
void app;
```
:::

### cookieOptions

Un objet permettant la configuration des attributs du cookie de session est attendu en valeur. La dépendance npm [express-session](https://github.com/expressjs/session) est utilisée. Pour la liste complète et le détail des options de configuration acceptèes, veuillez vous référer à la documentation des options liées au [cookie](https://github.com/expressjs/session?tab=readme-ov-file#cookie) de la dépendanc&#x65;*.*

Configuration par défaut :

- `maxAge` défini par la var d'env `SESSION_COOKIE_MAX_AGE` ou 60 minutes par défaut
- `secret` défini par la var d'env `SESSION_SECRET` (requise)
- `secure` défini par la var d'env `SECURE_COOKIE` ou *false* par défaut

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  // ...
  cookieOptions: {
    secure: process.env.NODE_ENV === 'production',
    httpOnly: process.env.NODE_ENV === 'production',
    sameSite: process.env.NODE_ENV === 'production' ? 'none' : false
  }
};

const { app } = await start(serverCfg);

// init your business logic here
void app;
```
:::

### corsOptions

Un objet permettant la configuration de la mécanique CORS est attendu en valeur. La dépendance npm [cors](https://github.com/expressjs/cors) est utilisée. Pour la liste complète et le détail des options de configuration acceptèes, veuillez vous référer à la documentation des [options de configuration](https://github.com/expressjs/cors?tab=readme-ov-file#configuration-options) de la dépendance.

Configuration par défaut : `{ origin: '*', allowedHeaders: '*' }`

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  // ...
  corsOptions: {
      origin: (origin, callback) => {
      if (!origin || WHITE_LIST.includes(origin)) {
        callback(null, true);
      } else {
        callback(new Error('Origin not allowed!'));
      }
    },
    credentials: true,
    methods: 'GET,HEAD,OPTIONS,PUT,PATCH,POST,DELETE',
    allowedHeaders: ['Origin', 'Content-Type', 'Accept', 'Authorization'],
    preflightContinue: false
  }
};

const { app } = await start(serverCfg);

// init your business logic here
void app;
```
:::

### routes

Une instance d'un *router Express* est attendu en valeur. Les routes et les fonctions middleware spécifiques à l'OAV seront alors chargées et initialisées par l'application *Express*.

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start } from '@fasstech/oip-starter-utils/server';
import routes from './routes.mjs';

const serverCfg = {
  routes
  // ...
};

const { app } = await start(serverCfg);

// init your business logic here
void app;
```

routes.mjs

```javascript
import express from 'express';

const router = express.Router();

// define your custom routes / middlewares here
// /!\ do not forget to add your custom routes to vite.config.js /!\

// Middleware exemple
router.use('/custom-api', (req, res, next) => {
  console.log('/custom-api middleware');
  next();
});

// Route exemple
router.get('/custom-api/test', (req, res) => {
  console.log('GET /custom-api/test');
  res.send({ message: 'Hello world!' });
});

export default router;
```
:::

### securityHeadersOptions

Un objet permettant la configuration des headers de sécurité est attendu en valeur. La dépendance npm [helmet](https://www.npmjs.com/package/helmet) est utilisée. Pour la liste complète et le détail des options de configuration acceptèes, veuillez vous référer à la documentation de la dépendance.

Configuration par défaut : `{ xPoweredBy: false }`

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start } from '@fasstech/oip-starter-utils/server';

const serverCfg = {
  // ...
  securityHeadersOptions: {
    crossOriginResourcePolicy: { 
      policy: "same-site",
    },
  },
};

const { app } = await start(serverCfg);

// init your business logic here
void app;
```
:::

# Méthode getPubSub

La méthode `getPubSub` permet de récupérer l'instance *PubSub*. Elle est initialisée grâce à la dépendance [@fasstech/rabbitmq-helper](https://github.com/fasst/fasst-rabbitmq-helper) qui nécessite un service *RabbitMQ*.

Signature : \*() => \****PubSub***

Exemple :

```javascript
import { getPubSub } from '@fasstech/oip-starter-utils/server';

const pubsub = getPubSub();
```

# Les utilitaires graphQL OK et KO

Les utilitaires `OK` et `KO` permettent de standardiser les réponses des resolvers graphQL de l'OAV.

Signature des fonctions :

- ***OK** = (additionalFields = \{}) => (\{ ok: true, ...additionalFields })*
- ***KO** = (error, additionalFields = \{}) => (\{ error, ok: false, ...additionalFields })*

Exemple :

:::CodeblockTabs
resolver.mjs

```javascript
import { OK, KO } from '@fasstech/oip-starter-utils/server';

export const getCustomer = (args, context) => {
  if (/* something */) {
    const error = new Error('Something goes wrong!');
    
    return KO(error, {
      firstName: null,
      lastName: null,
    });
  }
  
  return OK({ 
    firstName: 'John',
    lastName: 'Doe',
  });
};
```
:::

# Méthode handleTask&#x20;

La fonction `handleTask` est chargée de récupérer les messages liés aux tâches sur la queue *RabbitMQ* adéquate. Pour chaque message valide, elle démarre un nouveau processus enfant qui va exécuter le code de la tâche.

Il est nécessaire d'importer et de définir cette méthode comme *event consumer* dans l'index du server de votre projet. Ex. :

:::CodeblockTabs
index.mjs

```javascript
import { handleTask, start } from '@fasstech/oip-starter-utils/server';
import { queueService } from '@fasstech/rabbitmq-helper';

await start({ /* ... */ });

// Register a consumer to handle `events` messages
queueService.consumeMessage(`${process.env.OAV_ID}.events`, 0, handleTask);
```
:::

# L'utilitaire getEnv

:::BlockQuote
**\[warn]** La clé de la variable d'environnement passée en paramètre à `getEnv` doit être connue par le framework OIP.
:::

La fonction `getEnv` permet de résoudre la valeur d'une variable d'environnement depuis le code serveur de l'OAV.

Exemple :

```javascript
import { getEnv } from '@fasstech/oip-starter-utils/server';

const myVar = getEnv(MY_VAR);
```

# L'utilitaire validateResolverContext

:::hint{type="info"}
**\[info]**
&#x20;Il est possible de générer les resolvers des vues protégés par défaut en spécifiant l'option `--gen-secure-resolvers` à la commande du build des vues de l'OAV.Ex. : `npx oip-tools views generate --gen-secure-resolvers`
:::

La fonction `validateResolverContext` permet de valider le contexte d'appel d'un resolver d'une vue avant son exécution.

Une query ou une mutation graphQL d'une vue est protégée si le resolver associé implémente et appelle `validateResolverContext`.

Dans ce cas, si la query ou la mutation relative au resolver est appelée en dehors du contexte de la vue associée, une erreur est jetée.

Signature : \*(**expectedViewId**: string, **actualViewId**: string) => \****boolean***

Exemple d'un resolver protégé d'une vue :

```javascript
import { validateResolverContext } from '@fasstech/oip-starter-utils/server';

export const myResolver = (args, context) => {
  const { process } = context;

  // protected resolver, an error will be thrown if the resolver is called from outside the view
  validateResolverContext('expectedViewId', process.viewId);

  return {
    // ... resolved fields
  };
};

export default myResolver;
```
