¿Cuáles son las buenas prácticas para el diseño de schemas en GraphQL?

Question

IT Interview Practice · Accepted Answer

Un buen schema está **guiado por el cliente, es nullable por defecto en los bordes y evoluciona sin versiones**. Modela el dominio en los términos que los clientes usan realmente, no en tus tablas de base de datos.

## Nullability

Haz un campo non-null (`!`) solo cuando *siempre* puedas devolverlo. Abusar de `!` es una trampa: si un campo non-null da error, anula todo su objeto padre, convirtiendo un fallo pequeño en un gran vacío. Prefiere nullable para cualquier cosa que dependa de un servicio downstream.

```graphql
type User {
  id: ID!             # realmente siempre presente
  email: String!      # obligatorio en tu BD -> seguro como non-null
  avatarUrl: String   # viene de un servicio externo -> nullable, así su fallo queda aislado
}
```

## Nombres e inputs

- Usa nombres consistentes y descriptivos; los booleanos se leen como predicados (`isPublished`).
- Da a cada mutation un único tipo **`input`** y devuelve un tipo **payload**: podrás añadir campos más adelante sin romper la firma.

```graphql
input CreatePostInput { title: String!, body: String! }
type CreatePostPayload { post: Post!, errors: [UserError!]! }  # margen para crecer
type Mutation { createPost(input: CreatePostInput!): CreatePostPayload! }
```

## Evolución sin versionado

GraphQL evita las URLs `/v2`. Evolucionas de forma **aditiva**: añade campos libremente y retira los antiguos con `@deprecated` mientras los clientes migran.

```graphql
type User {
  fullName: String!
  name: String! @deprecated(reason: "Use fullName")   # sigue sirviéndose hasta que los clientes lo abandonen
}
```

Eliminar o renombrar un campo es el único cambio realmente incompatible, así que diseña para rara vez necesitarlo. Evita también filtrar la forma de la BD (expón `fullName`, no `first_name`/`last_name` si los clientes quieren un solo campo).

## Por qué es importante

Estas decisiones son las que separan un schema que dura años de uno contra el que los clientes pelean. Los entrevistadores lo usan para medir la **madurez en diseño de APIs**, especialmente el compromiso nullability/errores y la mentalidad de evolución aditiva, que son propios de GraphQL.

Nullability

Nombres e inputs

Evolución sin versionado

Por qué es importante

Preguntas relacionadas