API em Java: REST, GraphQL, gRPC — qual escolher em 2025?

Introdução: evolução das APIs em Java

O mundo do desenvolvimento Java não para. Há 10 anos, a escolha era óbvia: REST e JSON. Hoje, ao projetar uma arquitetura de microsserviços ou um aplicativo móvel, o desenvolvedor se depara com uma verdadeira variedade de protocolos. REST, GraphQL, gRPC — cada um promete maravilhas, mas na realidade, por trás de cada tecnologia existem compromissos.

Neste artigo, não vamos recontar a documentação. Vamos pegar um problema real: precisamos criar uma API para uma plataforma educacional (como nosso PythonLib, só que em Java). Temos cursos, alunos e progresso de aprendizado. E vamos tentar implementar o mesmo endpoint de três maneiras diferentes.

Vamos descobrir qual protocolo tornará seu código mais rápido e sua vida mais fácil.

API REST em Java: o clássico que nunca morre

REST (Representational State Transfer) é um estilo arquitetural, não um protocolo. Em Java, o padrão de facto para REST é o Spring Boot com suas anotações. Simplicidade, clareza, uma comunidade enorme — é por isso que amamos o REST.

Exemplo: obtendo lista de cursos

Suponha que precisamos enviar ao cliente uma lista de todos os cursos com informações básicas:

@RestController\n@RequestMapping("/api/courses")\npublic class CourseController {\n\n    @GetMapping\n    public ResponseEntity<List<CourseDTO>> getAllCourses() {\n        List<Course> courses = courseService.findAll();\n        List<CourseDTO> dtos = courses.stream()\n                .map(c -> new CourseDTO(c.getId(), c.getTitle(), c.getAuthor()))\n                .toList();\n        return ResponseEntity.ok(dtos);\n    }\n}

O cliente recebe JSON:

[\n  {"id": 1, "title": "Java para iniciantes", "author": "Ivan Petrov"},\n  {"id": 2, "title": "Spring Boot Masterclass", "author": "Anna Smirnova"}\n]

Vantagens do REST em Java:

\n
• Baixa barreira de entrada — qualquer desenvolvedor Java conhece Spring.
\n
• Cache via cabeçalhos HTTP (ETag, Cache-Control).
\n
• Amplo suporte de ferramentas (Postman, Swagger, OpenAPI).
\n

Desvantagens:

\n
• Problema de over-fetching (dados em excesso) e under-fetching (falta de dados, necessidade de várias requisições).
\n
• Tipagem fraca — tudo depende de um contrato que pode ser facilmente violado.
\n

REST é ideal para APIs públicas, quando os clientes são terceiros e você precisa de máxima compatibilidade. Mas se seu cliente for um aplicativo móvel que deseja receber exatamente o que precisa, o REST começa a irritar.

GraphQL em Java: me dê apenas o que eu peço

GraphQL é uma linguagem de consulta criada pelo Facebook. Em Java, é mais frequentemente implementado através da biblioteca graphql-java ou da integração com Spring — GraphQL Kickstart.

O próprio cliente decide quais campos precisa. Sem over-fetching. Uma única requisição — e você obtém os cursos junto com o progresso do aluno.

Exemplo: schema GraphQL e resolver

Definindo o schema:

type Course {\n    id: ID!\n    title: String!\n    author: String!\n    progress(studentId: ID!): Int\n}\n\ntype Query {\n    courses: [Course!]!\n}

Escrevendo o resolver em Java:

@Component\npublic class CourseResolver implements GraphQLQueryResolver {\n\n    @Autowired\n    private CourseService courseService;\n\n    public List<Course> courses() {\n        return courseService.findAll();\n    }\n}\n\n@Component\npublic class CourseFieldResolver implements GraphQLResolver<Course> {\n\n    @Autowired\n    private ProgressService progressService;\n\n    public Integer progress(Course course, Long studentId) {\n        return progressService.getProgress(course.getId(), studentId);\n    }\n}

Requisição do cliente:

query {\n  courses {\n    title\n