GraphQL vs REST — practical comparison for a developer portal API

APIs & Microservices
,
1

The honest comparison

REST shines when:

  • Simple CRUD operations
  • Public API with external consumers
  • Caching is critical (HTTP caching works naturally)
  • Team is small / less GraphQL experience
  • File uploads needed

GraphQL shines when:

  • Multiple clients with different data needs (mobile app needs less data than web)
  • Rapid frontend iteration without backend changes
  • Deeply nested data (avoid over/under-fetching)
  • Strong typing and introspection needed

Side-by-side example:

// REST — 3 round trips for a dashboard widget
GET /api/user/123
GET /api/user/123/projects
GET /api/user/123/notifications

// GraphQL — 1 request
query DashboardWidget($userId: ID!) {
  user(id: $userId) {
    name
    avatar
    projects(limit: 5) { id name status }
    notifications(unread: true) { id message }
  }
}

Our recommendation for a developer portal:

┌─────────────────────────────────────┐
│  Public/Partner APIs  →  REST       │  Stable, documented, cacheable
│  Internal BFF layer   →  GraphQL    │  Flexible, client-driven
│  Real-time features   →  WebSocket  │  Chat, live updates
│  File uploads         →  REST       │  GraphQL handles this poorly
└─────────────────────────────────────┘

For a Deloitte internal dev portal specifically: GraphQL with schema-first design (SDL) gives you auto-generated docs, type safety end-to-end with TypeScript, and lets frontend teams move without waiting for backend endpoint changes.