# GraphQL API {#graphql-api}


Ever Gauzy provides a **GraphQL API** alongside the REST API, offering a flexible, type-safe query language for frontend clients.



> [!IMPORTANT]
> The GraphQL API is currently a **Work-In-Progress (WIP)**. The REST API is the primary production API. GraphQL coverage is being expanded incrementally.




## Endpoint {#endpoint}


| Environment | GraphQL Endpoint                   | GraphQL Playground                 |
| ----------- | ---------------------------------- | ---------------------------------- |
| **Local**   | `http://localhost:3000/graphql`    | `http://localhost:3000/graphql`    |
| **Demo**    | `https://apidemo.gauzy.co/graphql` | `https://apidemo.gauzy.co/graphql` |


## Architecture {#architecture}


The GraphQL layer is built with `@nestjs/graphql` (Apollo Server):





```mermaid
graph LR
    A["GraphQL Request"] --> B["Resolver"]
    B --> C["Service"]
    C --> D["Repository"]
```






### Code-First Approach {#code-first-approach}


Gauzy uses the **code-first** approach where GraphQL schema is generated from TypeScript classes:

```typescript
// Object Type
@ObjectType()
export class Employee {
  @Field(() => ID)
  id: string;

  @Field()
  firstName: string;

  @Field()
  lastName: string;

  @Field({ nullable: true })
  startedWorkOn?: Date;
}

// Resolver
@Resolver(() => Employee)
export class EmployeeResolver {
  constructor(private readonly employeeService: EmployeeService) {}

  @Query(() => [Employee])
  async employees(): Promise<Employee[]> {
    return this.employeeService.findAll();
  }

  @Mutation(() => Employee)
  async createEmployee(
    @Args("input") input: CreateEmployeeInput,
  ): Promise<Employee> {
    return this.employeeService.create(input);
  }
}
```


## Example Queries {#example-queries}



### Query Employees {#query-employees}


```graphql
query {
  employees {
    id
    firstName
    lastName
    startedWorkOn
    user {
      email
    }
    organization {
      name
    }
  }
}
```


### Query with Variables {#query-with-variables}


```graphql
query GetEmployee($id: ID!) {
  employee(id: $id) {
    id
    firstName
    lastName
    skills {
      name
    }
  }
}
```


### Mutation {#mutation}


```graphql
mutation CreateEmployee($input: CreateEmployeeInput!) {
  createEmployee(input: $input) {
    id
    firstName
    lastName
  }
}
```


## Authentication {#authentication}


GraphQL requests require the same JWT authentication as REST:

```bash
POST /graphql
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "query": "query { employees { id firstName } }"
}
```


## GraphQL Playground {#graphql-playground}


When running in development mode, the GraphQL Playground is available at the `/graphql` endpoint. It provides:

- Interactive query editor
- Schema exploration
- Auto-completion
- Documentation browser
- Request history


## Configuration {#configuration}


```typescript
// app.module.ts
GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  autoSchemaFile: true, // Code-first schema generation
  playground: process.env.NODE_ENV !== "production",
  introspection: true,
  context: ({ req, res }) => ({ req, res }),
});
```


## REST vs GraphQL {#rest-vs-graphql}


| Feature            | REST                     | GraphQL                       |
| ------------------ | ------------------------ | ----------------------------- |
| **Maturity**       | ✅ Production-ready      | ⚠️ Work-in-progress           |
| **Coverage**       | ✅ All endpoints         | ⚠️ Partial coverage           |
| **Documentation**  | ✅ Swagger UI            | ✅ Playground                 |
| **Data fetching**  | Fixed response shape     | Client-defined response shape |
| **Over-fetching**  | Possible                 | Eliminated                    |
| **Under-fetching** | Multiple requests needed | Single request                |
| **Caching**        | HTTP caching             | Apollo Client caching         |


## Related Pages {#related-pages}


- [REST API](https://sourcey-gauzy.pages.dev/api/rest-api/index.md) — primary REST API documentation
- [API Overview](https://sourcey-gauzy.pages.dev/api/overview/index.md) — general API information