API REST vs GraphQL — Choisir la bonne architecture

Le débat REST vs GraphQL est souvent présenté comme un choix binaire. En réalité, les deux ont leurs forces et leurs faiblesses selon le contexte.

REST — Principes et forces

REST (Representational State Transfer) est basé sur les ressources HTTP.

GET    /articles          → Liste des articles
GET    /articles/42       → Article #42
POST   /articles          → Créer un article
PUT    /articles/42       → Modifier l'article #42
DELETE /articles/42       → Supprimer l'article #42

Avantages REST

• Cache HTTP natif — Les GET sont cachables par les CDN
• Simplicité — Facilement compréhensible par tous
• Tooling mature — Swagger, Postman, etc.
• Stateless — Pas de session côté serveur

GraphQL — Principes et forces

GraphQL est un langage de requête pour votre API.

query {
  article(id: 42) {
    title
    excerpt
    author {
      name
      avatar
    }
    category {
      name
      color
    }
  }
}

Avantages GraphQL

• No over-fetching — Vous demandez exactement ce dont vous avez besoin
• No under-fetching — Une seule requête pour plusieurs ressources
• Typage fort — Le schema est auto-documenté
• Parfait pour le mobile — Économise la bande passante

Comparaison directe

Implémentation Laravel

REST avec Laravel Resources

class ArticleResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id'       => $this->id,
            'title'    => $this->title,
            'excerpt'  => $this->excerpt,
            'author'   => new UserResource($this->whenLoaded('author')),
            'category' => new CategoryResource($this->whenLoaded('category')),
        ];
    }
}

GraphQL avec Lighthouse

# schema.graphql
type Article {
    id: ID!
    title: String!
    content: String!
    author: User! @belongsTo
    category: Category @belongsTo
}

type Query {
    articles: [Article!]! @paginate
    article(id: ID! @eq): Article @find
}

Quand choisir quoi ?

Choisissez REST si :

• API publique consommée par des tiers
• Besoins simples CRUD
• Cache agressif nécessaire
• Équipe peu familière avec GraphQL

Choisissez GraphQL si :

• Application mobile avec bande passante limitée
• Frontend complexe avec des vues très différentes
• BFF (Backend For Frontend)
• Agrégation de plusieurs sources de données

La troisième voie : tRPC

Pour les projets full-stack TypeScript, tRPC offre une alternative intéressante : type-safe de bout en bout sans code generation.

// Serveur
export const articleRouter = router({
  list: publicProcedure.query(async () => {
    return db.article.findMany();
  }),
  byId: publicProcedure
    .input(z.object({ id: z.number() }))
    .query(async ({ input }) => {
      return db.article.findUnique({ where: { id: input.id } });
    }),
});

// Client — 100% type-safe automatiquement
const { data } = trpc.article.byId.useQuery({ id: 42 });