HTTP, JSON and REST APIs: How Web Backends Talk

https://api.example.com:8443/api/expenses/42?month=2026-09#details\___/   \_____________/\___/\_____________/ \__________/ \_____/scheme       host      port      path          query     fragment

// File: Main.javaimport com.sun.net.httpserver.HttpExchange;import com.sun.net.httpserver.HttpServer;import java.io.BufferedReader;import java.io.IOException;import java.io.InputStreamReader;import java.io.OutputStream;import java.net.InetSocketAddress;import java.net.Socket;import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.nio.charset.StandardCharsets;import java.util.Map;import java.util.TreeMap;public class Main {    // A tiny in-memory "expenses" resource. It stores whatever JSON text it is given and does no validation.    static final Map<Integer, String> STORE = new TreeMap<>();    static int nextId = 2;    static void handle(HttpExchange exchange) throws IOException {        String method = exchange.getRequestMethod();        String[] parts = exchange.getRequestURI().getPath().split("/");   // "", "expenses", maybe "1"        Integer id = parts.length > 2 ? Integer.valueOf(parts[2]) : null;        String body = new String(exchange.getRequestBody().readAllBytes(), StandardCharsets.UTF_8);        String contentType = exchange.getRequestHeaders().getFirst("Content-Type");        if (id == null) {                                                    // the collection: /expenses            switch (method) {                case "GET" -> send(exchange, 200, "[" + String.join(",", STORE.values()) + "]");                case "POST" -> {                    if (contentType == null || !contentType.startsWith("application/json")) {                        send(exchange, 415, "{\"error\":\"send application/json\"}");                        return;                    }                    int newId = nextId++;                    STORE.put(newId, body);                    exchange.getResponseHeaders().add("Location", "/expenses/" + newId);                    send(exchange, 201, body);                }                default -> {                    exchange.getResponseHeaders().add("Allow", "GET, POST");                    send(exchange, 405, "{\"error\":\"method not allowed\"}");                }            }            return;        }        switch (method) {                                                    // one item: /expenses/{id}            case "GET" -> {                String found = STORE.get(id);                send(exchange, found == null ? 404 : 200, found == null ? "{\"error\":\"not found\"}" : found);            }            case "PUT" -> {                STORE.put(id, body);                                         // replace, or create at this id                send(exchange, 200, body);            }            case "DELETE" -> {                if (STORE.remove(id) == null) {                    send(exchange, 404, "{\"error\":\"not found\"}");                } else {                    send(exchange, 204, null);                }            }            default -> {                exchange.getResponseHeaders().add("Allow", "GET, PUT, DELETE");                send(exchange, 405, "{\"error\":\"method not allowed\"}");            }        }    }    static void send(HttpExchange exchange, int status, String body) throws IOException {        if (body == null) {            exchange.sendResponseHeaders(status, -1);                        // no body        } else {            byte[] bytes = body.getBytes(StandardCharsets.UTF_8);            exchange.getResponseHeaders().add("Content-Type", "application/json");            exchange.sendResponseHeaders(status, bytes.length);            try (OutputStream out = exchange.getResponseBody()) {                out.write(bytes);            }        }        exchange.close();    }    static void rawExchange(int port) throws IOException {        String request = "GET /expenses/1 HTTP/1.1\r\n"                + "Host: localhost\r\n"                + "Accept: application/json\r\n"                + "Connection: close\r\n"                + "\r\n";        System.out.println("--- bytes sent by the client ---");        System.out.print(request.replace("\r\n", "\n"));        System.out.println("--- bytes received ---");        try (Socket socket = new Socket("127.0.0.1", port)) {            socket.getOutputStream().write(request.getBytes(StandardCharsets.US_ASCII));            BufferedReader in = new BufferedReader(new InputStreamReader(socket.getInputStream(), StandardCharsets.UTF_8));            String line;            while ((line = in.readLine()) != null) {                if (!line.startsWith("Date:")) {                             // the time changes on every run                    System.out.println(line);                }            }        }        System.out.println();    }    static void call(HttpClient client, String method, String url, String contentType, String body) throws Exception {        HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(url));        HttpRequest.BodyPublisher publisher = body == null                ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(body);        builder.method(method, publisher);        if (contentType != null) {            builder.header("Content-Type", contentType);        }        HttpResponse<String> response = client.send(builder.build(), HttpResponse.BodyHandlers.ofString());        String path = URI.create(url).getPath();        StringBuilder line = new StringBuilder(String.format("%-6s %-14s -> %d", method, path, response.statusCode()));        response.headers().firstValue("Location").ifPresent(v -> line.append("  Location: ").append(v));        response.headers().firstValue("Allow").ifPresent(v -> line.append("  Allow: ").append(v));        System.out.println(line);    }    public static void main(String[] args) throws Exception {        STORE.put(1, "{\"id\":1,\"amountCents\":1250,\"description\":\"lunch with Sam\"}");        HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);        server.createContext("/expenses", exchange -> {            try {                handle(exchange);            } catch (Exception e) {                e.printStackTrace();                exchange.sendResponseHeaders(500, -1);                exchange.close();            }        });        server.start();        int port = server.getAddress().getPort();        String base = "http://127.0.0.1:" + port;        try {            rawExchange(port);            HttpClient client = HttpClient.newHttpClient();            String json = "application/json";            String item = "{\"amountCents\":450,\"description\":\"bus\"}";            call(client, "GET", base + "/expenses/1", null, null);            call(client, "GET", base + "/expenses/99", null, null);            call(client, "POST", base + "/expenses", json, item);            call(client, "POST", base + "/expenses", json, item);            call(client, "POST", base + "/expenses", "text/plain", "450 bus");            call(client, "PUT", base + "/expenses/1", json, item);            call(client, "PUT", base + "/expenses/1", json, item);            call(client, "DELETE", base + "/expenses/2", null, null);            call(client, "DELETE", base + "/expenses/2", null, null);            call(client, "PATCH", base + "/expenses/1", json, item);            call(client, "DELETE", base + "/expenses", null, null);            System.out.println("stored now: " + STORE.keySet());        } finally {            server.stop(0);        }    }}

--- bytes sent by the client ---GET /expenses/1 HTTP/1.1Host: localhostAccept: application/jsonConnection: close--- bytes received ---HTTP/1.1 200 OKContent-type: application/jsonContent-length: 58{"id":1,"amountCents":1250,"description":"lunch with Sam"}GET    /expenses/1    -> 200GET    /expenses/99   -> 404POST   /expenses      -> 201  Location: /expenses/2POST   /expenses      -> 201  Location: /expenses/3POST   /expenses      -> 415PUT    /expenses/1    -> 200PUT    /expenses/1    -> 200DELETE /expenses/2    -> 204DELETE /expenses/2    -> 404PATCH  /expenses/1    -> 405  Allow: GET, PUT, DELETEDELETE /expenses      -> 405  Allow: GET, POSTstored now: [1, 3]

{  "id": 42,  "description": "lunch with Sam",  "amountCents": 1250,  "paid": true,  "category": null,  "tags": ["work", "shared"],  "receipt": { "number": "R-17", "pages": 1 }}

// File: src/main/java/com/example/jsondemo/JsonDemo.javapackage com.example.jsondemo;import java.time.LocalDate;import java.util.List;import tools.jackson.core.JacksonException;import tools.jackson.core.type.TypeReference;import tools.jackson.databind.SerializationFeature;import tools.jackson.databind.json.JsonMapper;public class JsonDemo {    record Expense(long id, LocalDate spentOn, long amountCents, String category, String description) {    }    record NewExpense(LocalDate spentOn, long amountCents, String category, String description) {    }    static void tryRead(JsonMapper mapper, String label, String json) {        try {            System.out.println(label + ": " + mapper.readValue(json, NewExpense.class));        } catch (JacksonException e) {            String message = e.getOriginalMessage();            if (message.length() > 90) {                message = message.substring(0, 90) + "...";             // the full message is very long            }            System.out.println(label + ": " + e.getClass().getSimpleName() + " - " + message);        }    }    public static void main(String[] args) {        JsonMapper mapper = JsonMapper.builder().build();        JsonMapper pretty = JsonMapper.builder().enable(SerializationFeature.INDENT_OUTPUT).build();        Expense expense = new Expense(1, LocalDate.of(2026, 9, 3), 1250, "FOOD", "lunch with Sam");        System.out.println("Java object to JSON:");        System.out.println(pretty.writeValueAsString(expense));        String body = "{\"spentOn\":\"2026-09-05\",\"amountCents\":4500,\"category\":\"TRANSPORT\","                + "\"description\":\"metro pass\"}";        NewExpense received = mapper.readValue(body, NewExpense.class);        System.out.println("JSON to Java object:");        System.out.println(received);        String list = "[{\"id\":1,\"spentOn\":\"2026-09-03\",\"amountCents\":1250,\"category\":\"FOOD\",\"description\":\"a\"},"                + "{\"id\":2,\"spentOn\":\"2026-09-05\",\"amountCents\":4500,\"category\":\"TRANSPORT\",\"description\":null}]";        List<Expense> expenses = mapper.readValue(list, new TypeReference<List<Expense>>() { });        System.out.println("A JSON array becomes a list of " + expenses.size() + ", the second description is "                + expenses.get(1).description());        System.out.println("Bad input:");        tryRead(mapper, "missing fields    ", "{\"amountCents\":100}");        tryRead(mapper, "unknown field     ", "{\"amountCents\":100,\"colour\":\"red\"}");        tryRead(mapper, "wrong type        ", "{\"amountCents\":\"lots\"}");        tryRead(mapper, "invalid date      ", "{\"spentOn\":\"05/09/2026\",\"amountCents\":100}");        tryRead(mapper, "not JSON at all   ", "{\"amountCents\": }");    }}

Java object to JSON:{  "id" : 1,  "spentOn" : "2026-09-03",  "amountCents" : 1250,  "category" : "FOOD",  "description" : "lunch with Sam"}JSON to Java object:NewExpense[spentOn=2026-09-05, amountCents=4500, category=TRANSPORT, description=metro pass]A JSON array becomes a list of 2, the second description is nullBad input:missing fields    : NewExpense[spentOn=null, amountCents=100, category=null, description=null]unknown field     : NewExpense[spentOn=null, amountCents=100, category=null, description=null]wrong type        : InvalidFormatException - Cannot deserialize value of type `long` from String "lots": not a valid `long` valueinvalid date      : InvalidFormatException - Cannot deserialize value of type `java.time.LocalDate` from String "05/09/2026": Failed to...not JSON at all   : StreamReadException - Unexpected character ('}' (code 125)): expected a value

GET    /api/expenses             list expenses (supports filtering and paging)POST   /api/expenses             create an expenseGET    /api/expenses/42          read onePUT    /api/expenses/42          replace onePATCH  /api/expenses/42          change some fieldsDELETE /api/expenses/42          delete oneGET    /api/expenses/summary     an aggregate view of the collection

{  "type": "https://example.com/problems/validation-error",  "title": "Invalid expense",  "status": 400,  "detail": "amountCents must be greater than zero",  "instance": "/api/expenses"}