GraphQL API Design Guide

# GraphQL API Design Guide for Google Antigravity

Master GraphQL API development with Google Antigravity IDE. This comprehensive guide covers schema design, resolvers, dataloaders, subscriptions, authentication, and performance optimization patterns for building flexible, efficient APIs.

## Configuration

Configure your Antigravity environment for GraphQL:

```typescript
// .antigravity/graphql.ts
export const graphqlConfig = {
  features: {
    subscriptions: true,
    dataloaders: true,
    federation: false,
    persisted: true
  },
  security: {
    depthLimit: 10,
    complexityLimit: 1000
  }
};
```

## Schema Design

Define type-safe schemas:

```typescript
import { gql } from "graphql-tag";

export const typeDefs = gql`
  scalar DateTime

  type Query {
    user(id: ID!): User
    users(filter: UserFilter, pagination: PaginationInput): UserConnection!
    post(id: ID!): Post
    posts(filter: PostFilter): [Post!]!
  }

  type Mutation {
    createUser(input: CreateUserInput!): CreateUserPayload!
    updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
    createPost(input: CreatePostInput!): CreatePostPayload!
  }

  type User {
    id: ID!
    email: String!
    name: String
    posts(first: Int, after: String): PostConnection!
    createdAt: DateTime!
  }

  type Post {
    id: ID!
    title: String!
    content: String
    published: Boolean!
    author: User!
    createdAt: DateTime!
  }

  input CreateUserInput {
    email: String!
    name: String
    password: String!
  }

  type CreateUserPayload {
    user: User
    errors: [Error!]
  }

  type Error {
    field: String
    message: String!
  }
`;
```

## DataLoader Pattern

Batch and cache requests:

```typescript
import DataLoader from "dataloader";
import { db } from "../db";

export function createLoaders() {
  return {
    userById: new DataLoader<string, User>(async (ids) => {
      const users = await db.user.findMany({
        where: { id: { in: [...ids] } }
      });

      const userMap = new Map(users.map(u => [u.id, u]));
      return ids.map(id => userMap.get(id) || null);
    }),

    postsByAuthor: new DataLoader(async (keys) => {
      const authorIds = keys.map(k => k.authorId);

      const posts = await db.post.findMany({
        where: { authorId: { in: authorIds } },
        orderBy: { createdAt: "desc" }
      });

      const postsByAuthor = new Map<string, Post[]>();
      posts.forEach(post => {
        const existing = postsByAuthor.get(post.authorId) || [];
        postsByAuthor.set(post.authorId, [...existing, post]);
      });

      return keys.map(key => postsByAuthor.get(key.authorId) || []);
    })
  };
}
```

## Best Practices

Follow these guidelines for GraphQL:

1. **Use DataLoaders** - Batch and cache requests
2. **Implement pagination** - Cursor-based for large sets
3. **Design mutations carefully** - Return payloads with errors
4. **Add query complexity** - Prevent expensive queries
5. **Use persisted queries** - Improve security and caching
6. **Type everything** - Full TypeScript coverage

Google Antigravity IDE provides intelligent GraphQL schema suggestions and resolver optimization.