---
title: Editer le schéma GQL
slug: oip-next/v3/schema-graphql
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-13T11:47:03.000Z
---

Côté serveur, Apollo Server v4 est utilisé pour gérer la couche GraphQL, tandis qu’Apollo Client v3 est utilisé côté client. La documentation officielle d’Apollo est disponible  [ici](https://www.apollographql.com/docs/apollo-server/)

L'interface [Apollo Sandbox,](https://www.apollographql.com/docs/graphos/explorer/sandbox/) qui permet de visualiser le schéma complet GraphQL et de tester les queries et mutations, est accessible par défaut via l'URL : [http://localhost:5500/graphql](http://localhost:5500/graphql)

# Ajouter des types GraphQL

Pour tout ajout au schema GraphQL géré par le serveur, ajoutez vos types, queries ou mutations dans le dossier `server/graphql`

Dossier de travail :

:::CodeblockTabs
Tree

```none
server/graphql
├─ resolvers/
│   ├─ mutations/
│   ├─ queries/
│   └─ index.mjs
├─ types/
│   ├─ index.mjs
│   ├─ mutation-type.mjs
│   └─ query-type.mjs
└─ index.mjs
```
:::

## Ajouter un type

1. &#x20;Ajoutez le fichier de votre type gql dans `server/graphql/types`

Exemple du type `Business` fichier `business-type.mjs`

:::CodeblockTabs
business-type.mjs

```javascript
import { gql } from 'graphql-tag';

export const BusinessType = gql`
  type Business {
    message: String
    isSomething: Boolean
  }
`;
```
:::

2. &#x20;Ajoutez ensuite l'export du fichier depuis `server/graphql/types/index.mjs`

:::CodeblockTabs
index.mjs

```javascript
...
export * from './business-type.mjs';
```
:::

3. &#x20;Enfin ajoutez le type aux `typeDefs` depuis le fichier `server/graphql/index.mjs`

:::CodeblockTabs
index.mjs

```javascript
export * from './resolvers/index.mjs';
import {
  ...
  BusinessType
} from './types/index.mjs';

export const BusinessTypeDefs = [
  ...
  BusinessType
];
```
:::

## Ajouter un input type

Répétez les mêmes étapes que pour l'ajout d'un type.

1. &#x20;Ajoutez le fichier de votre input type gql dans `server/graphql/types`

Attention de définir votre input type avec `input` et non `type`

:::CodeblockTabs
business-input-type.mjs

```javascript
import { gql } from 'graphql-tag';

export const BusinessInputType = gql`
  input BusinessInputType {
    message: String
    isSomething: Boolean
  }
`;
```
:::

2. &#x20;Ajoutez ensuite l'export du fichier depuis `server/graphql/types/index.mjs`

:::CodeblockTabs
index.mjs

```javascript
...
export * from './business-type.mjs';
export * from './business-input-type.mjs';
```
:::

3. &#x20;Enfin ajoutez l'input type aux `typeDefs` depuis le fichier `server/graphql/index.mjs`

:::CodeblockTabs
index.mjs

```javascript
export * from './resolvers/index.mjs';
import {
  ...
  BusinessType,
  BusinessInputType,
} from './types/index.mjs';

export const BusinessTypeDefs = [
  ...
  BusinessType,
  BusinessInputType,
];
```
:::

## Ajouter un response type

1. &#x20;Répétez les mêmes étapes que pour l'ajout d'un type.

Exemple :

:::CodeblockTabs
business-response-type.mjs

```javascript
import { gql } from 'graphql-tag';

// an example of response type, implements QueryResponse type defined from `@fasstech/oip-starter-utils`
export const BusinessResponseType = gql`
  type BusinessResponse implements QueryResponse {
    ok: Boolean!
    error: String
    business: Business
  }
`;
```
:::

2. &#x20;Dans cet exemple, le type `BusinessResponse` implémente le type `QueryResponse` défini dans le fichier `query-type.mjs` contenu dans le dossier `server` de la dépendance `@fasstech/oip-starter-utils`

&#x20;Path : `@fasstech/oip-starter-utils/server/graphql/types/query-type.mjs`

## Ajouter une query

1. &#x20;Ajoutez le type de la query dans le fichier `server/graphql/types/query-type.mjs`

Exemple :

:::CodeblockTabs
query-type.mjs

```javascript
import { gql } from 'graphql-tag';

// the query type
export const QueryType = gql `
  extend type Query {
    # add your queries here
    business: BusinessResponse
  }
`;
```
:::

2. &#x20;Ajoutez le fichier du resolver de la query dans le dossier `server/graphql/resolvers/queries`

Exemple du fichier `business-resolver.mjs`

:::CodeblockTabs
business-resolver.mjs

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

// an example of query resolver
export const businessResolver = ({ process, sessionId }) => {
  const { projectId } = process;
  logger.info(`[Resolver][business-exemple] sessionId=${sessionId} projectId=${projectId}`);
  return OK({
    business: {
      message: 'hello world!',
      isSomething: true
    }
  });
};
```
:::

3. Exportez le fichier depuis `server/graphql/resolvers/queries/index.mjs`

:::CodeblockTabs
index.mjs

```javascript
...
export * from './business-resolver.mjs';
```
:::

4. Enfin, ajoutez le resolver au resolver du type query depuis le fichier `server/graphql/resolvers/index.mjs`

:::CodeblockTabs
index.mjs

```javascript
import { businessResolver } from './queries/index.mjs';

export const businessResolvers = {
  Query: {
    business: (parent, args, context) => businessResolver(context)
  },
  Mutation: {
    ...
  }
};
```
:::

## Ajouter une mutation

1. &#x20;Ajoutez le type de la mutation dans le fichier `server/graphql/types/mutation-type.mjs`

Exemple :

:::CodeblockTabs
mutation-type.mjs

```javascript
import { gql } from 'graphql-tag';

// the mutation type
export const MutationType = gql`
  extend type Mutation {
    # add your mutations here
    createBusiness(input: BusinessInputType!): BusinessResponse
  }
`;
```
:::

2. Ajoutez le fichier du resolver de la query dans le dossier `server/graphql/resolvers/mutations`

Exemple du fichier `create-business-resolver.mjs`

:::CodeblockTabs
create-business-resolver.mjs

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

// an example of mutation resolver
export const createBusinessResolver = (context, { input }) => {
  const { message, isSomething } = input;
  logger.info(`[Resolver][create-business-exemple] message=${message} isSomething=${isSomething}`);
  return OK({
    business: {
      message,
      isSomething
    }
  });
};
```
:::

3. &#x20;Exportez le fichier depuis `server/graphql/resolvers/mutations/index.mjs`

:::CodeblockTabs
index.mjs

```javascript
...
export * from './create-business-resolver.mjs';
```
:::

4. &#x20;Enfin, ajoutez le resolver au resolver du type mutation depuis le fichier `server/graphql/resolvers/index.mjs`

:::CodeblockTabs
index.mjs

```javascript
import { businessResolver } from './queries/index.mjs';
import { createBusinessResolver } from './mutations/index.mjs';

export const businessResolvers = {
  Query: {
    business: (parent, args, context) => businessResolver(context)
  },
  Mutation: {
    createBusiness: (parent, args, context) => createBusinessResolver(context, args)
  }
};

```
:::

# Côté client

Dossier de travail :

```none
app/
├─ graphql/
│   ├─ fragments/
│   ├─ mutations/
│   ├─ queries/
│   └─ index.js
└─ hooks/
    └─ index.js
```

## Ajouter une query ou une mutation

***Les types gql associés doivent être préalablement définis côté server ainsi que la nouvelle query ou mutation***

Ajoutez les queries ou mutations dans le dossier `app/graphql` dans les sous-dossiers `queries` ou `mutations`, respectivement.

Exemple d'une query, fichier, fichier `business.js`

:::CodeblockTabs
business.js

```javascript
import { gql } from '@apollo/client';

export const BusinessQuery = gql`
  query BusinessQuery {
    business {
      business {
        message
        isSomething
      }
      ok
      error
    }
  }
`;
```
:::

Exemple d'une mutation, fichier `create-business.js`

:::CodeblockTabs
create-business.js

```javascript
import { gql } from '@apollo/client';

export const CreateBusiness = gql`
  mutation CreateBusiness($input: BusinessInputType!) {
    createBusiness(input: $input) {
      business {
        message
        isSomething
      }
      ok
      error
    }
  }
`;
```
:::

## Ajouter le hook associé

Si la nouvelle query ou mutation doit être utilisée dans les vues, déclarez le hook associé dans le dossier `app/hooks`

Exemple d'un hook pour une query, fichier `use-query-example.hook.js`

:::CodeblockTabs
use-query-example.hook.js

```javascript
import { useQuery } from '@apollo/client';
import { BusinessQuery } from '../graphql/index.js';

export const useBusinessQuery = (args) => {
  const { data, error, loading, refetch } = useQuery(BusinessQuery, args);

  return {
    error,
    loading,
    refetch,
    business: data?.business?.business || {}
  };
};
```
:::

Exemple d'un hook pour une mutation, fichier `use-mutation-example.hook.js`

:::CodeblockTabs
use-mutation-example.hook.js

```javascript
import { useCommitMutation } from '@@views/_common/hooks/useCommitMutation';
import { CreateBusiness } from '../graphql/index.js';

export const useCreateCustomerMutation = () => {
  return useCommitMutation(CreateBusiness, { dataProp: 'createBusiness'});
};
```
:::

## Depuis une vue

Importer le hook respectif pour consommer la nouvelle query ou mutation depuis une vue ou un composant d'une vue.

Exemple :

:::CodeblockTabs
MyView\.jsx

```javascript
import { 
  useBusinessQuery,
  useCreateCustomerMutation 
} from '@@appHooks';

const MyView = () => {
  // query
  const { business, loading, error } = useBusinessQuery();

  // mutation
  const { 
    onFormSubmit: mutate,
    loading,
    error 
  } = useCreateCustomerMutation();

  // on mutate
  const onMutate = () => {
    mutate({
      message: 'is magic',
      isSomething: true
    }, (ok, error, data) => {
      if (!ok) {
        console.error(error);
        return;
      }
      console.log(data);
    });
  };
  
  return (
    <div>
      ...
    
      <div>
        <p>Business:</p>
        <pre>{JSON.stringify(business, null, 2)}</pre>
      </div>
      
      <button onClick={onMutate}>MUTATE</button>
    </div>
  );
};

export default MyView;
```
:::

## Depuis un handler personnalisé

Veuillez vous référer à la documentation sur [les handlers personnalisés](https://doc.fasst.tech/oip-project-starter/process-handlers#lK4DV) pour exécuter une nouvelle query ou une mutation depuis un handler personnalisé.
