laravel-api-graphql

Laravel 13 GraphQL — Lighthouse, Federation & Schema Design

When to Use

Use this skill when implementing GraphQL APIs in Laravel 13 using Lighthouse. GraphQL solves over-fetching and under-fetching problems inherent in REST. Best suited for mobile apps, dashboards, complex frontends, and aggregated data systems. Not every project needs GraphQL — simple CRUD APIs are better served by REST or JSON:API. This skill covers schema design, directives, resolvers, validation, authentication, N+1 prevention with DataLoader, query complexity protection, subscriptions, and Federation for distributed graphs.

---

When to Choose GraphQL

Good Candidates

✓ Mobile apps (bandwidth constrained)
✓ Dashboards and analytics UIs
✓ Complex frontend applications
✓ Aggregated data from multiple backends
✓ Public APIs for developer ecosystems
✓ Real-time features (subscriptions)

Avoid For

✗ Simple CRUD APIs (REST is simpler)
✗ File upload/download servers
✗ Internal microservice communication (use gRPC)
✗ Logging and monitoring endpoints

---

Lighthouse Installation & Setup

composer require nuwave/lighthouse

php artisan vendor:publish --tag=lighthouse-schema
php artisan vendor:publish --tag=lighthouse-config

# Optional: GraphQL IDE
composer require mll-lab/laravel-graphiql --dev

Configuration

// config/lighthouse.php
return [
    'route' => [
        'uri' => '/graphql',
        'name' => 'graphql',
        'middleware' => [
            \Illuminate\Routing\Middleware\ThrottleRequests::class . ':api',
        ],
    ],

    'guard' => ['api'],

    'schema' => [
        'register' => base_path('graphql/schema.graphql'),
    ],

    'cache' => [
        'enable' => env('LIGHTHOUSE_CACHE_ENABLE', false),
        'key' => 'lighthouse-schema',
    ],

    'debug' => env('APP_DEBUG', false),
];

---

Schema-First Design

Always Define Schema Before Resolvers

# graphql/schema.graphql

type Query {
    me: User! @auth
    users: [User!]! @paginate
    user(id: ID! @eq): User @find
    posts: [Post!]! @paginate
    post(id: ID! @eq): Post @find
}

type Mutation {
    createUser(input: CreateUserInput! @spread): User! @create
    updateUser(id: ID!, input: UpdateUserInput! @spread): User! @update
    deleteUser(id: ID!): User @delete
    login(email: String!, password: String!): AuthPayload!
}

type User {
    id: ID!
    name: String!
    email: String!
    posts: [Post!]! @hasMany
    created_at: DateTime!
    updated_at: DateTime!
}

type Post {
    id: ID!
    title: String!
    content: String!
    author: User! @belongsTo
    comments: [Comment!]! @hasMany
    created_at: DateTime!
}

type Comment {
    id: ID!
    body: String!
    author: User! @belongsTo
    post: Post! @belongsTo
}

input CreateUserInput {
    name: String! @rules(apply: ["required", "string", "max:255"])
    email: String! @rules(apply: ["required", "email", "unique:users,email"])
    password: String! @rules(apply: ["required", "string", "min:8"])
}

input UpdateUserInput {
    name: String @rules(apply: ["string", "max:255"])
    email: String @rules(apply: ["email", "unique:users,email"])
}

type AuthPayload {
    token: String!
    user: User!
}