Build a Lightweight Java API from Scratch

TL;DR: in this article, I cover how you can create a lightweight Java API which processes an HTTP request without using any external libraries.
This is part one of a two part article - in the second part, I discuss the design patterns I used to make handling requests super simple!

The Brief

Recently, I have been helping my Dad with his project by writing a consumer for his Natural Language Processing Java library, Enguage. I want to expose his interpret function - which takes in natural language and creates a response - as an API on the web, to which I can send a POST request.
The API didn’t need to be secure or scalable; just easily available as an endpoint to any client so that we could easily create a POC consumer without needing to port the library itself - just make an HTTP request.
An example request would be:
> curl -X POST \ -H "Content-Type: application/json" \ -d '{"sessionId": "<SESSION_ID>", "utterance": "what do I need?"}' \ https://<ENDPOINT>/interpret > you don't need anything

Listening to HTTP Requests and Sending a Simple Response creates the ServerSocket and listens on port 8080. It also instantiates a new instance of the Enguage library, to be used within the requests.
// package opt.api; import; import; import org.enguage.Enguage; import opt.api.utils.RequestHandler; public class Server { static private int port = 8080; static public int port() { return port; } static public void server( int port ) { try (ServerSocket server = new ServerSocket( port, 5 )) { System.out.println("Listening on port " + port() ); while (true) new RequestHandler( server.accept() ).run(); } catch (IOException e) { e.printStackTrace(); } } public static void main( String arg[]) { // Instantiate the library Enguage.set( new Enguage() ); server( port() ); } } is the entry point for all HTTP requests, it opens with a try-with-resources block which instantiates a BufferReader in and DataOutputStream out. We haven’t used in yet, however we will eventually read the HTTP request for the POST headers and body from it.
To send a simple response, we do out.writeBytes(response) and then connection.close().
// package opt.api.utils; import; import; import; import; public class RequestHandler extends Thread { private Socket connection; public RequestHandler( Socket conn ) { connection = conn; } private String response = "200 OK"; private String response() { return response; } public void response( String s ) { response = s; } public void run() { try ( BufferedReader in = new BufferedReader( new InputStreamReader(connection.getInputStream()) ); DataOutputStream out = new DataOutputStream(connection.getOutputStream()); ) { String response = "HTTP/1.1 " + response() +"\n" + "Content-Type: text/plain\n" + "Content-Length: " + "<SOME_REPLY_GOES_HERE>".length() + "\n" + "\n" + "<SOME_REPLY_GOES_HERE>\n"; out.writeBytes(response); connection.close(); } catch (Exception e) { e.printStackTrace(); } } }
With these two files, we have enough to send and receive HTTP requests!
You can now build it with javac and run it with java Server to get Listening on port 8080. Sending out cURL request, we would get the same response to every request we make - but we’re going to go further to parse the request and send a response which changes with the request!

Parsing the HTTP Request

Getting the HTTP String from the BufferedReader

I wrote a class to convert the input stream into a string that I could parse later:
// package opt.api.utils.http; import; import; import; import; public class HttpStringBuilder { public static String build(BufferedReader in) throws IOException { StringBuilder requestBuilder = new StringBuilder(); String headerLine; while ((headerLine = in.readLine()) != null && !headerLine.trim().isEmpty()) { requestBuilder.append(headerLine).append("\r\n"); } String postHeaderCrlf = "\r\n"; requestBuilder.append(postHeaderCrlf); int contentLength = getBodyContentLength(requestBuilder.toString().trim()); char[] buffer = new char[contentLength]; int bytesRead =, 0, contentLength); if (bytesRead > 0) { requestBuilder.append(buffer, 0, bytesRead); } return requestBuilder.toString().trim(); } // method to extract the Content-Length from the request headers private static int getBodyContentLength(String request) { String[] headerLines = request.split("\r\n"); for (String lineMixedCase : headerLines) { String line = lineMixedCase.toLowerCase(); if (line.toLowerCase().contains("content-length: ")) { int contentLength = Integer.parseInt(line.split("content-length: ")[1]); return contentLength; } } return 0; } }

Parsing the String into Body and Headers

Under the hood, HTTP requests (at layer 7 of the OSI model), is just an ASCII string that looks something like this:
Method Request-URI HTTP-Version Header-field: Header-value Request-Body
Or in our case,
POST /interpret HTTP/1.1 Content-Type: application/json Content-Length: 50 {"sessionId": "1", "utterance": "what do I need?"}
Once we have the string, we can simply extract the headers and parse the body.
I took a very MVP approach to this (as I didn’t want to spend too much time worrying about edge cases I didn’t care about, such as path parameters). If you are adapting this for your own needs, you will need to expand this (or use a library that does it for you). I’m writing this to show that reading an HTTP request is simply a case of string parsing.
Copy this code at your own peril!
// package opt.api.utils.http; import java.util.HashMap; import java.util.Map; public class HttpParser { public static Map<String, String> parseHeaders(String httpRequestString) { Map<String, String> parsedData = new HashMap<>(); // Split the request into header and body sections String[] requestParts = httpRequestString.split("\\r\\n\\r\\n", 2); String headerSection = requestParts[0]; // Extract the HTTP method and route from the header String[] headerLines = headerSection.split("\\r\\n"); String firstLine = headerLines[0]; String[] firstLineParts = firstLine.split(" "); String method = firstLineParts[0]; String route = firstLineParts[1].substring(1, firstLineParts[1].length()); String http = firstLineParts[2]; parsedData.put("method", method); parsedData.put("route", route); parsedData.put("http", http); for (int i = 1; i<headerLines.length; i++) { String[] header = headerLines[i].split(": ", 2); if (header.length == 2) { parsedData.put(header[0].trim(), header[1].trim()); } } return parsedData; } public static Map<String, String> parseBody(String httpRequestString) { Map<String, String> parsedData = new HashMap<>(); // Split the request into header and body sections String[] requestParts = httpRequestString.split("\r\n\r\n", 2); String bodySection = requestParts.length > 1 ? requestParts[1] : ""; if (bodySection.trim().length() == 0) return parsedData; Map<String, String> meta = parseHeaders(httpRequestString); String contentType = meta.get("content-type"); if ("application/json".equalsIgnoreCase(contentType)) { // Assuming the body contains JSON data Map<String, String> bodyMap = parseJson(bodySection.trim()); return bodyMap; } return parsedData; } private static Map<String, String> parseJson(String jsonBody) { Map<String, String> bodyMap = new HashMap<>(); int i = 1; // Skip the first '{' while (i < jsonBody.length() - 1) { StringBuilder key = new StringBuilder(); StringBuilder value = new StringBuilder(); while (jsonBody.charAt(i) != ':') { key.append(jsonBody.charAt(i)); i++; } i++; // skip the ':' i++; // skip the whitespace after ':' // Parse the value int braceCount = 0; while (i < jsonBody.length() - 1) { char currentChar = jsonBody.charAt(i); if (currentChar == '{' || currentChar == '[') { braceCount++; } else if (currentChar == '}' || currentChar == ']') { braceCount--; } else if (currentChar == ',' && braceCount == 0) { break; } value.append(currentChar); i++; } // Skip the whitespace after the value and the ',' (if any) i++; while (i < jsonBody.length() && Character.isWhitespace(jsonBody.charAt(i))) { i++; } // Add the key-value pair to the map bodyMap.put( key.toString().toLowerCase().replace("\"", "").trim(), value.toString().replace("\"", "").trim() ); i++; // move to the next character } return bodyMap; } }

RequestHandler Updated

Now that we have the request parsed, my is updated:
// package opt.api.utils; ... import opt.api.routing.Router; import opt.api.utils.http.HttpParser; import opt.api.utils.http.HttpStringBuilder; import opt.api.utils.http.HttpException; public class RequestHandler extends Thread { ... private HttpResponseBuilder responseBuilder = new HttpResponseBuilder(); public void run() { try ( BufferedReader in = new BufferedReader( new InputStreamReader(connection.getInputStream()) ); DataOutputStream out = new DataOutputStream(connection.getOutputStream()); ) { String request =; Map<String, String> head = HttpParser.parseHeaders(request); Map<String, String> body = HttpParser.parseBody(request); String response =, body); out.writeBytes(response); connection.close(); } catch (Exception e) { e.printStackTrace(); } } }
I have passed the parsed head and body into the, body) method which should handle passing back a response. I will link the code to this extraction here, but know that under the hood, it just calls router.handle(head, body).
I’ll leave it up to you to create HttpResponseBuilder for yourself for your own use case.
My code for HttpResponseBuilder was:
// HttpResponseBuilder: package opt.api.utils.http; import java.util.Map; import opt.api.routing.Router; public class HttpResponseBuilder { private String response = "200 OK"; private String response() {return response;} public void response( String s ) {response = s;} private Router router = new Router(); public String build (Map<String, String> head, Map<String, String> body) { String reply; try { reply = router.handle(head, body); } catch (HttpException e) { reply = e.getErrorMessage(); response(e.getResponse()); } String response = head.get("http") + " " + response() +"\n" + "Content-Type: text/plain\n" + "Content-Length: " + reply.length() + "\n" + "\n" + reply + "\n"; return response; } }


The above guidelines demonstrate how to write a simple Java API and dispel some of the mystery surrounding frameworks that abstract away much of the low-level complexity of dealing with web requests. This knowledge can help developers understand what happens "under the hood” when frameworks deal with requests.

Next Steps

Read part two to see how I implemented the router design pattern.
Read this article on how I deployed this to with BitBucket Pipelines.