java 40 lines · 9 steps

Calling the GitHub API with Java's HttpClient

A small client fetches a GitHub user over HTTP, maps status codes to exceptions, and deserializes JSON into a record.

Explained by highlit
Intermediate http-client json-deserialization error-handling rest-api records
1public class GitHubUserClient {
2 
3 private final HttpClient http = HttpClient.newBuilder()
4 .connectTimeout(Duration.ofSeconds(10))
5 .followRedirects(HttpClient.Redirect.NORMAL)
6 .build();
7 
8 private final ObjectMapper mapper = new ObjectMapper()
9 .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
10 
11 public GitHubUser fetchUser(String username) throws IOException, InterruptedException {
12 HttpRequest request = HttpRequest.newBuilder()
13 .uri(URI.create("https://api.github.com/users/" + username))
14 .header("Accept", "application/vnd.github+json")
15 .header("User-Agent", "acme-service/1.0")
16 .timeout(Duration.ofSeconds(15))
17 .GET()
18 .build();
19 
20 HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString());
21 
22 int status = response.statusCode();
23 if (status == 404) {
24 throw new NoSuchElementException("No GitHub user named " + username);
25 }
26 if (status >= 400) {
27 throw new IOException("GitHub API returned " + status + ": " + response.body());
28 }
29 
30 return mapper.readValue(response.body(), GitHubUser.class);
31 }
32 
33 public record GitHubUser(
34 long id,
35 String login,
36 String name,
37 @JsonProperty("public_repos") int publicRepos,
38 @JsonProperty("html_url") String profileUrl) {
39 }
40}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1A shared, pre-configured HttpClient with sensible timeouts is cheaper and safer than building one per request.
  2. 2Translating HTTP status codes into meaningful exceptions gives callers a clean, domain-oriented error contract.
  3. 3Records plus @JsonProperty give a compact, immutable target for JSON that tolerates unexpected fields.

Related explainers

ruby 
class Order
  class InvalidTransition < StandardError; end
 
  TRANSITIONS = {

A state machine for order transitions in Ruby

state-machine data-driven error-handling
Intermediate 8 steps
java 
public class SlidingLogRateLimiter {
 
    private final int maxRequests;
    private final long windowMillis;

How a sliding-log rate limiter works

rate-limiting concurrency sliding-window
Advanced 8 steps
java 
public final class Slugifier {
 
    private static final Pattern NON_LATIN = Pattern.compile("[^\\w-]");
    private static final Pattern WHITESPACE = Pattern.compile("[\\s]+");

Building a URL slugifier in Java

regex unicode-normalization string-processing
Intermediate 8 steps
rust 
use std::cmp::Ordering;
use std::str::FromStr;
 
#[derive(Debug, Clone, PartialEq, Eq)]

Parsing and ordering semantic versions in Rust

parsing trait-implementation ordering
Intermediate 8 steps
javascript 
'use client';
 
import { useEffect } from 'react';
import * as Sentry from '@sentry/nextjs';

How a Next.js error boundary recovers

error-boundary error-handling observability
Intermediate 8 steps
ruby 
class Registration < ApplicationRecord
  belongs_to :event
 
  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }

Validating registrations in Rails

validations i18n error-handling
Intermediate 8 steps

Share this explainer

Here's the card — post it anywhere.

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