---
title: API Server
slug: oip-next/v3/starter-utils/api-server
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-13T12:22:12.000Z
---

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`

Les imports depuis l'OAV :

```javascript
import {
  start,
  getPubSub,
  OK,
  KO
} 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`

Ex. :

:::CodeblockTabs
index.mjs

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

const serverCfg = {
  // options
};

const { app } = await startServer(serverCfg);

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

## Options requises

### graphql

Un objet qui contient la liste des définitions des types et des resolvers graphQL de l'OAV est attendu en valeur. Ex. :

:::CodeblockTabs
index.mjs

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

const serverCfg = {
  graphql: {
    resolvers: { /* ... */ },
    typeDefs: { /* ... */ }
  }
  // ...
};

const { app } = await startServer(serverCfg);

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

:::BlockQuote
**\[info]** À partir de la version 3.4.5 de *@fasstech/oip-starter-utils*, l'option `graphql` accepte également une propriété optionnelle `security`
:::

:::BlockQuote
**\[info]** À partir de la version 3.7.0 de *@fasstech/oip-starter-utils*, l'option `graphql.security` accepte deux propriétés optionnelles supplémentaires :
\- `maxCoercionErrors`
\- `maxErrors`
:::

La propriété `graphql.security` permet de configurer certaines limites de protection contre les attaques de type *DoS* au niveau de l'endpoint graphQL.

Un objet de configuration est attendu en valeur de la forme suivante :

```javascript
const security = {
  payloadLimit: '50kb',
  armorConfig: { /* ...graphql-armor config */ },
  maxCoercionErrors: 50,
  maxErrors: 10
};
```

- la propriété `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*.
- la propriété `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.
- la propriété `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.
- la propriété `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/)

Concernant l'option `graphql.security.armorConfig`, *@fasstech/oip-starter-utils* utilise par défaut les valeurs de la configuration par défaut de la lib *graphql-armor* sauf pour la limite `costLimit.maxCost` qui est définie sur `100` au lieu de `5000`

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.

Ex. :

:::CodeblockTabs
index.mjs

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

const serverCfg = {
  graphql: {
    // ...
    security: {
      payloadLimit: '1kb',
      maxCoercionErrors: 20,
      maxErrors: 5,
      armorConfig: {
        maxDepth: {
          n: 3,
        },
        costLimit: {
          maxCost: 20,
        },
        maxTokens: {
          n: 100,
        },
      },
    },
  },
  // ...
};

const { app } = await startServer(serverCfg);

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

### session

:::BlockQuote
**\[info]** À partir de la version **3.4.1**, `sessionId` qui correspond à l’identifiant de la session de navigation en cours, est désormais transmis en paramètre à la callback de résolution de l’entité Project.
:::

Un objet qui contient les méthodes de résolution de l'entité *Project* à partir du contexte client est attendu en valeur. Ex. :

:::CodeblockTabs
index.mjs

```javascript
import { start as startServer } from '@fasstech/oip-starter-utils/server';
import { initProjectFromContext } from './init-project-from-context.mjs';
import { getMockContext } from './get-mock-context.mjs';

const serverCfg = {
  session: {
    resolveMockProject: () => initProjectFromContext(getMockContext()),
    resolveProject: initProjectFromContext
  }
  // ...
};

const { app } = await startServer(serverCfg);

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

init-project-from-context.mjs

```javascript
import { Entities } from '@fasstech/oip-core';

export const initProjectFromContext = async (context) => {
  // setup your init logic project here

  const { externalId } = context;
  let project = await Entities('Project').get({ externalId });
  if (project) {
    return project;
  }

  project = await Entities('Project').create({ externalId });
  project = await Entities('Project').save(project);
  return project;
};
```

get-mock-context.mjs

```javascript
import * as crypto from 'crypto';

export const getMockContext = () => {
  const randomId = crypto.randomUUID();

  // edit your mock context here

  return {
    externalId: `mock-project_${randomId}`,
    projectName: 'Mock Project',
    projectDescription: 'Mock Project Description'
  };
};

```
:::

Se référer à cette [documentation](https://doc.fasst.tech/oip-project-starter/auth-et-logique-de-session#oK4sn) pour plus de détails.

:::BlockQuote
**\[info]** À partir de la version **3.4.6**, l'option `session` accepte également une propriété optionnelle `resolveContext` qui 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 de `resolveContext` : *async (token) => context*

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 { resolveContext } from './resolve-context.mjs';

const serverCfg = {
  session: {
    resolveMockProject,
    resolveProject,
    resolveContext,
  }
  // ...
};

const { app } = await startServer(serverCfg);

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

resolve-context.mjs

```javascript
export const resolveContext = async (token) => {
  // your logic

  // ex.:
  const context = await asyncCall('api/url', token);

  if (!context) {
    throw new Error('TOKEN_VALIDATION_FAILED');
  }

  return context;
}
```
:::

:::BlockQuote
**\[info]** À partir de la version **3.8.0**, l'option `session` accepte également une propriété optionnelle `resolveMetadata` qui permet de définir la fonction de rappel de résolution des métadonnées de session.
:::

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 }**) => **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.

Exemple :

:::CodeblockTabs
index.mjs

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

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

const { app } = await startServer(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;
}
```
:::

### businessRoutes

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

:::CodeblockTabs
index.mjs

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

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

const { app } = await startServer(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;
```
:::

Se référer à cette [documentation](https://doc.fasst.tech/oip-project-starter/guidelines#ZdUm1) pour plus de détails.

### extendProcess

À partir de la version 3.4.1, le sessionId est désormais accessible depuis l’objet Process reçu en paramètre de la callback extendProcess.

La callback qui permet d'étendre le type *Process* est attendue en valeur. Cette callback reçoit en paramètre l'objet *Process*. Ex. :

:::CodeblockTabs
index.mjs

```javascript
import { start as startServer } from '@fasstech/oip-starter-utils/server';
import { extendProcess } from './extend-process.mjs';

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

const { app } = await startServer(serverCfg);

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

extend-process.mjs

```javascript
export const extendProcess = async (process) => {
  // resolve custom fields from your process here
  // additional fields must match type definition at server/graphql/types/extended-process-type.mjs

  return {
    ...process
    // additional fields
  };
};
```
:::

Se référer à cette [documentation](https://doc.fasst.tech/oip-project-starter/process#U1s9V) pour plus de détails.

### logger

:::BlockQuote
**\[info]** Propriété disponible à partir de la version **3.8.0** de la bibliothèque.
:::

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

Exemple :

:::CodeblockTabs
index.mjs

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

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

const { app } = await startServer(serverCfg);

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

## Options optionnelles

### basePath

:::BlockQuote
**\[info]** Disponible à partir de la version **3.8.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`
- `/graphqlwsurl`
- `/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
// /graphql       -> /api/graphql
// /graphqlwsurl  -> /api/graphqlwsurl

const { app } = await start(serverCfg);

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

### corsOptions

Option disponible à partir de la version 3.4.0

Un objet permettant la configuration de la mécanique CORS est attendu en valeur. La lib utilise la dépendance npm [cors](https://github.com/expressjs/cors). 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 npm [cors](https://github.com/expressjs/cors?tab=readme-ov-file#configuration-options)

Ex. :

:::CodeblockTabs
index.mjs

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

const WHITE_LIST = [ /* URLs */ ]

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 startServer(serverCfg);

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

Se référer à cette [documentation](https://doc.fasst.tech/oip-project-starter/guidelines#jnKC9) pour plus de détails.

### cookieOptions

Option disponible à partir de la version 3.4.0

Un objet permettant la configuration des attributs du cookie de session est attendu en valeur. La lib utilise la dépendance npm [express-session](https://github.com/expressjs/session). 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* de la dépendance npm [express-session](https://github.com/expressjs/session)

Ex. :

:::CodeblockTabs
index.mjs

```javascript
import { start as startServer } 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 startServer(serverCfg);

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

Se référer à cette [documentation](https://doc.fasst.tech/oip-project-starter/auth-et-logique-de-session#0Lpno) pour plus de détails.

### resolveFirstView

Option disponible à partir de la version 3.4.0

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

:::CodeblockTabs
index.mjs

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

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

const { app } = await startServer(serverCfg);

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

resolve-first-view\.mjs

```javascript
import { Entities } from '@fasstech/oip-core';

export const resolveFirstView = async (projectId, process) => {
  // pour gérer la reprise du parcours
  if (process) {
    return process.viewId; // ou autre viewId
  }
  
  // récupération de l'entité Project
  const project = await Entities('Project').get({ id: projectId });
  
  // votre logique
  
  return 'my-desired-view-id';
};
```
:::

Se référer à cette [documentation](https://doc.fasst.tech/oip-project-starter/les-transitions#eIa_Z) pour plus de détails.

### dataProtectionConfigPath

Option disponible à partir de la version 3.4.4

Le *path* du fichier de configuration des règles de politiques de données de l'OAV est attendu en valeur. Ex. :

:::CodeblockTabs
index.mjs

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

const serverCfg = {
  // ...
  dataProtectionConfigPath: './data-protection.config.mjs',
};

const { app } = await startServer(serverCfg);

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

### helmetConfig

Option disponible à partir de la version 3.6.0

Un objet permettant la configuration des headers de sécurité est attendu en valeur. La lib utilise la dépendance npm [helmet](https://www.npmjs.com/package/helmet). 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.

Ex. :

:::CodeblockTabs
index.mjs

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

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

const { app } = await startServer(serverCfg);

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

# Méthode getPubSub

La méthode `getPubSub` permet de récupérer l'instance *PubSub* nécessaire à la gestion  des subscriptions graphQL. L'instance *PubSub&#x20;*&#x64;oit être définie au niveau du fichier de configuration OIP de l'OAV. Ex. :

:::CodeblockTabs
oip.config.mjs

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

export default {
  debug: true,
  database: {
    url: process.env.OIP_MONGO_DB_URL
  },
  rabbitMQ: {
    name: 'fasst-oip-core'
  },
  views: {
    config: '../viewsConfig'
  },
  tasks: {
    // ...
  },
  pubsub: getPubSub() // PubSub
};
```
:::

L'instance *PubSub* est initialisée grâce à la dépendance [@fasstech/rabbitmq-helper](https://github.com/fasst/fasst-rabbitmq-helper) qui nécessite un service *RabbitMQ*.

# 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 })*

Ex. :

:::CodeblockTabs
getCustomer.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',
  });
};
```
:::
