Aadhaar masking API in Java

Multipart without a library

The JDK's HttpClient has no multipart body publisher, which is why most Java examples reach for Apache HttpClient or OkHttp. It is about twenty lines to build the body yourself, and it removes a dependency from a service that handles identity documents — worth doing once and keeping.

import java.io.ByteArrayOutputStream;
import java.net.URI;
import java.net.http.*;
import java.nio.file.*;

final class Multipart {
    private static final String BOUNDARY = "----MaskAadhaar" + System.nanoTime();

    // Builds a single-file multipart/form-data body. The boundary must not appear
    // inside the payload; a nanoTime suffix makes that collision impossible in practice.
    static HttpRequest.BodyPublisher fileBody(Path path) throws Exception {
        var out = new ByteArrayOutputStream();
        var header = "--" + BOUNDARY + "\r\n"
            + "Content-Disposition: form-data; name=\"file\"; filename=\""
            + path.getFileName() + "\"\r\n"
            + "Content-Type: application/octet-stream\r\n\r\n";

        out.write(header.getBytes());
        out.write(Files.readAllBytes(path));
        out.write(("\r\n--" + BOUNDARY + "--\r\n").getBytes());

        return HttpRequest.BodyPublishers.ofByteArray(out.toByteArray());
    }

    static String contentType() {
        return "multipart/form-data; boundary=" + BOUNDARY;
    }
}

With that in place the call itself is short:

var client = HttpClient.newHttpClient();

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.maskaadhaar.com/api/v1/mask-aadhaar"))
    .header("X-API-Key", System.getenv("MASKAADHAAR_KEY"))
    .header("Content-Type", Multipart.contentType())
    .POST(Multipart.fileBody(Path.of("aadhaar.jpg")))
    .build();

var res = client.send(request, HttpResponse.BodyHandlers.ofByteArray());
Files.write(Path.of("aadhaar_masked.jpg"), res.body());

System.out.println("redacted "
    + res.headers().firstValue("X-Masked-Count").orElse("0") + " region(s)");

A client you can ship

The same call with the three rules applied: a retry policy that distinguishes transient failures from permanent ones, a checked outcome rather than a bare byte array, and no path by which the document or the key reaches a log.

import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.*;
import java.nio.file.Path;
import java.time.Duration;
import java.util.Set;

public class AadhaarMasker {

    private static final String API = "https://api.maskaadhaar.com/api/v1";

    // rate_limited clears in seconds and processing_failed is safe to retry once.
    // quota_exceeded shares status 429 but will not clear until the month resets,
    // so retrying it only delays the moment somebody finds out.
    private static final Set<String> RETRYABLE = Set.of("rate_limited", "processing_failed");

    private final HttpClient http = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();
    private final ObjectMapper json = new ObjectMapper();
    private final String apiKey = System.getenv("MASKAADHAAR_KEY");

    public record Result(byte[] masked, int regions, int quotaRemaining) {}

    public static class MaskingException extends Exception {
        public final String code;
        MaskingException(String code, String message) {
            super(code + ": " + message);
            this.code = code;
        }
    }

    // 200 OK, but no Aadhaar number was found: the original came back unchanged.
    public static class NotMaskedException extends MaskingException {
        NotMaskedException() {
            super("no_number_found", "No Aadhaar number detected; document needs review");
        }
    }

    public Result mask(Path path) throws Exception {
        long delayMs = 2_000;
        HttpResponse<byte[]> res = null;

        for (int attempt = 0; attempt < 4; attempt++) {
            // The body is rebuilt each attempt. A BodyPublisher is not reusable once
            // subscribed, and a reused one sends nothing.
            var req = HttpRequest.newBuilder()
                    .uri(URI.create(API + "/mask-aadhaar"))
                    .header("X-API-Key", apiKey)
                    .header("Content-Type", Multipart.contentType())
                    .timeout(Duration.ofSeconds(60))
                    .POST(Multipart.fileBody(path))
                    .build();

            res = http.send(req, HttpResponse.BodyHandlers.ofByteArray());
            if (res.statusCode() == 200) break;

            // Errors are JSON with a stable machine-readable `error` field.
            var node = json.readTree(res.body());
            var code = node.path("error").asText("unknown");

            if (!RETRYABLE.contains(code) || attempt == 3) {
                throw new MaskingException(code, node.path("message").asText(""));
            }

            Thread.sleep(delayMs);
            delayMs *= 2;
        }

        int regions = Integer.parseInt(
                res.headers().firstValue("X-Masked-Count").orElse("0"));

        // Calling a zero count a success is how an unmasked Aadhaar number ends up in
        // a folder marked redacted.
        if (regions == 0) throw new NotMaskedException();

        int remaining = Integer.parseInt(
                res.headers().firstValue("X-Quota-Remaining").orElse("-1"));

        return new Result(res.body(), regions, remaining);
    }
}

Both exception types are checked rather than runtime, deliberately. A caller that forgets to handle NotMaskedException will not compile, which is the whole point: the compiler enforces the one rule that this API most needs callers to follow.

Async and batch

For a backlog, sendAsync plus a bounded semaphore keeps you under the rate limit without a scheduler or a queue.

import java.util.concurrent.*;
import java.util.*;

// Bounded by the plan's rate limit rather than by available cores.
private static final Semaphore GATE = new Semaphore(8);

public BatchReport maskAll(List<Path> paths) throws InterruptedException {
    var review = Collections.synchronizedList(new ArrayList<Path>());
    var failed = Collections.synchronizedList(new ArrayList<Path>());
    var done   = Collections.synchronizedList(new ArrayList<Path>());

    try (var pool = Executors.newVirtualThreadPerTaskExecutor()) {
        for (Path p : paths) {
            pool.submit(() -> {
                GATE.acquire();
                try {
                    var r = masker.mask(p);
                    Files.write(outputFor(p), r.masked());
                    done.add(p);
                } catch (AadhaarMasker.NotMaskedException e) {
                    review.add(p);
                } catch (Exception e) {
                    failed.add(p);
                } finally {
                    GATE.release();
                }
                return null;
            });
        }
    }

    // All three lists matter. A report that gives only `done` is indistinguishable
    // from one that quietly left a hundred Aadhaar numbers in the clear.
    return new BatchReport(done, review, failed);
}

Virtual threads (Java 21 and later) suit this well: the tasks are almost entirely blocked on network I/O, so platform threads would sit idle at a much higher cost. The semaphore, not the thread count, is what keeps you inside the rate limit. For the arithmetic behind sizing a large run, see bulk Aadhaar masking.

Questions

How do I mask an Aadhaar number in Java?

Build a multipart/form-data body and POST it to https://api.maskaadhaar.com/api/v1/mask-aadhaar with your key in the X-API-Key header. The JDK's java.net.http.HttpClient can do this without any third-party HTTP library once you write a small multipart body publisher. The response body is the masked document; read the X-Masked-Count header to confirm it was actually masked.

Does java.net.http.HttpClient support multipart uploads?

Not directly — the JDK ships no multipart BodyPublisher. Building one is about twenty lines: write the boundary, a Content-Disposition header naming the part 'file', the file bytes, and the closing boundary, then wrap it in BodyPublishers.ofByteArray. That removes a dependency from a service handling identity documents.

Do I need Apache HttpClient or OkHttp?

No. They are convenient, but the only thing they add here is the multipart body, which is short enough to own. Fewer dependencies in a service that processes Aadhaar documents is worth a few lines of code.

How should Spring Boot call the masking API?

Register the client as a bean and run the call on an @Async task executor sized to your plan's requests-per-minute. Calling it on a servlet thread ties up the thread for as long as OCR takes and times out under load.

Why should NotMasked be a checked exception?

Because the single most damaging mistake with this API is treating a 200 response with X-Masked-Count of zero as a success. Making it checked means a caller that forgets to handle it will not compile, so the compiler enforces the rule rather than a code reviewer having to catch it.

Related

• Aadhaar Masking API — endpoints, formats and how detection works
• Aadhaar PDF masking API — multi-page e-Aadhaar handling
• Bulk Aadhaar masking — throughput, back-off and cost at volume
• The same integration in Python
• The same integration in Node.js
• Integration guide — the language-agnostic walkthrough