java 41 lines · 7 steps

Calling the GitHub API with Spring WebClient

A reactive Spring service that wraps GitHub's REST API with a preconfigured WebClient and typed responses.

Explained by highlit
Spring Intermediate reactive http-client dependency-injection error-handling json-mapping
1@Service
2public class GitHubClient {
3 
4 private final WebClient webClient;
5 
6 public GitHubClient(WebClient.Builder builder) {
7 this.webClient = builder
8 .baseUrl("https://api.github.com")
9 .defaultHeader(HttpHeaders.ACCEPT, "application/vnd.github+json")
10 .build();
11 }
12 
13 public Mono<Repository> getRepository(String owner, String name) {
14 return webClient.get()
15 .uri("/repos/{owner}/{name}", owner, name)
16 .retrieve()
17 .onStatus(HttpStatusCode::is4xxClientError, response ->
18 Mono.error(new RepositoryNotFoundException(owner + "/" + name)))
19 .bodyToMono(Repository.class);
20 }
21 
22 public Flux<Repository> listRepositories(String owner) {
23 return webClient.get()
24 .uri(uriBuilder -> uriBuilder
25 .path("/users/{owner}/repos")
26 .queryParam("sort", "updated")
27 .queryParam("per_page", 50)
28 .build(owner))
29 .retrieve()
30 .bodyToFlux(Repository.class);
31 }
32 
33 public record Repository(
34 Long id,
35 String name,
36 @JsonProperty("full_name") String fullName,
37 @JsonProperty("html_url") String url,
38 @JsonProperty("stargazers_count") int stars,
39 @JsonProperty("private") boolean isPrivate) {
40 }
41}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Configuring a WebClient once in the constructor centralizes base URL and headers for every call.
  2. 2Mono and Flux let you model single versus multiple results without blocking threads.
  3. 3onStatus turns HTTP error codes into meaningful domain exceptions instead of generic failures.

Related explainers

python 
from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, status
from pydantic import BaseModel, EmailStr
from sqlalchemy.orm import Session
 

Building a signup endpoint in FastAPI

dependency-injection request-validation background-tasks
Intermediate 8 steps
java 
public interface GitHubClient {
 
    @GetExchange("/users/{username}")
    GitHubUser getUser(@PathVariable String username);

Declarative HTTP clients in Spring

http-client declarative-api proxy
Intermediate 8 steps
ruby 
class TemplateInterpolator
  PLACEHOLDER = /\{\{\s*([\w.]+)\s*\}\}/
 
  def initialize(strict: false)

Interpolating templates with dotted keys in Ruby

regex string-interpolation hash-traversal
Intermediate 6 steps
java 
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

Building a trie for autocomplete in Java

trie prefix-tree recursion
Intermediate 8 steps
php 
<?php
 
namespace App\Providers;
 

Subdomain multi-tenancy routing in Laravel

multi-tenancy service-container route-binding
Advanced 7 steps
go 
package config
 
import (
	"fmt"

A thread-safe config singleton in Go

singleton concurrency environment-variables
Intermediate 7 steps

Share this explainer

Here's the card — post it anywhere.

Calling the GitHub API with Spring WebClient — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code