Framework-less REST API in Java
Tags: restapi, java, framework
Published: 2018-12-29 01:59:42

---
title: Framework-less REST API in Java
published: true
description: Do you really need a framework? Think twice.
tags: REST API, Java, Framework
---

![Photo by Hieu Vu Minh on Unsplash](https://thepracticaldev.s3.amazonaws.com/i/bp5s7ju2fnxa5t7p7ckx.jpg)

Java ecosystem is packed with frameworks and libraries. 
For sure not as many as in JavaScript world and they don't get old as quickly too but still this fact causes that I dare to think that we've already forgotten how to create a completely framework-less applications.

You may say: [Spring](https://spring.io/) is a standard, why to re-invent a wheel. [Spark](http://sparkjava.com/) is a nice small REST framework. 
[Light-rest-4j](https://doc.networknt.com/getting-started/light-rest-4j/) is yet another.

I tell you, sure, you're right. You get a lot of bells and whistles with a framework, but you also get a lot of magic, learning overhead, additional features which you'll most likely not use and bugs as well. 

The more external code is there in your service the more chance its developers made some mistakes.

Open source community is active and there's a great chance that these bugs in framework will be fixed soon, but still I'd like to encourage you to re-think if you really need a framework.

If you're doing a small service or a console application maybe you can live without it.

What you could gain (or loose) by sticking to pure java code? Think of these: 

* your code could be much cleaner and predictable (or a complete mess if you're a bad coder)
* you'd have more control over your code, you won't be constrained by a framework (but you'd have to often write own code for what framework give you out of the box)
* your application would deploy and start much quicker, because the framework code does not need to initialise dozen of classes (or not start at all if you messed up the stuff, e.g. multi-threading)
* if you deploy your app on Docker, your images could be much slimmer because your jar would be slimmer too

I did a little experiment and tried developing a framework-less REST API. 

I thought it could be interesting from learning perspective and a bit refreshing.

When I started building this I often came across situations when I missed some features which Spring provides out of the box.

At that times, instead of switching on another Spring capability, I had to rethink it and develop it myself.

It occurred that for real business case I would probably still prefer to use Spring instead of reinventing a wheel.

Still, I believe the exercise was pretty interesting experience.

## Beginning.

I will go through this exercise step by step but not always paste a complete code here.
You can always checkout each step from a separate branch of the [git repository] (https://github.com/piczmar/pure-java-rest-api).

Create a fresh Maven project with an initial `pom.xml` file:

```
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.consulner.httpserver</groupId>
  <artifactId>pure-java-rest-api</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <java.version>11</java.version>
    <maven.compiler.source>${java.version}</maven.compiler.source>
    <maven.compiler.target>${java.version}</maven.compiler.target>
  </properties>
  
  <dependencies></dependencies>
</project>
```

Include java.xml.bind module dependency because those modules were removed in JDK 11 by [JEP-320](http://openjdk.java.net/jeps/320).

```xml
<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>2.4.0-b180608.0325</version>
</dependency>
```
and [Jackson](https://medium.com/r/?url=https%3A%2F%2Fgithub.com%2FFasterXML%2Fjackson) for JSON serialization

```xml
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.9.7</version>
</dependency>

```
Then we will use [Lombok](https://medium.com/r/?url=https%3A%2F%2Fprojectlombok.org%2F) to simplify POJO classes: 

```xml
<dependency>
  <groupId>org.projectlombok</groupId>
  <artifactId>lombok</artifactId>
  <version>1.18.0</version>
  <scope>provided</scope>
</dependency>
```

and [vavr](https://medium.com/r/?url=http%3A%2F%2Fwww.vavr.io%2F) for functional programming facilities

```xml
<dependency>
  <groupId>io.vavr</groupId>
  <artifactId>vavr</artifactId>
  <version>0.9.2</version>
</dependency>
```

I started from empty `Application` main class. 

You can get an initial code from [step-1](https://medium.com/r/?url=https%3A%2F%2Fgithub.com%2Fpiczmar%2Fpure-java-rest-api%2Ftree%2Fstep-1)  branch.

## First endpoint


The starting point of the web application is `com.sun.net.httpserver.HttpServer` class. 
The most simple `/api/hello` endpoint could look as below: 


```java
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;

import com.sun.net.httpserver.HttpServer;

class Application {

    public static void main(String[] args) throws IOException {
        int serverPort = 8000;
        HttpServer server = HttpServer.create(new InetSocketAddress(serverPort), 0);
        server.createContext("/api/hello", (exchange -> {
            String respText = "Hello!";
            exchange.sendResponseHeaders(200, respText.getBytes().length);
            OutputStream output = exchange.getResponseBody();
            output.write(respText.getBytes());
            output.flush();
            exchange.close();
        }));
        server.setExecutor(null); // creates a default executor
        server.start();
    }
}
```
When you run main program it will start web server at port `8000` and expose out first endpoint which is just printing `Hello!`, e.g. using curl:

```bash
curl localhost:8000/api/hello
```

Try it out yourself from [step-2](https://medium.com/r/?url=https%3A%2F%2Fgithub.com%2Fpiczmar%2Fpure-java-rest-api%2Ftree%2Fstep-2) branch.


## Support different HTTP methods
Our first endpoint works like a charm but you will notice that no matter which HTTP method you'll use it will respond the same.
E.g.: 

```bash
curl -X POST localhost:8000/api/hello
curl -X PUT localhost:8000/api/hello
```

The first gotcha when building the API ourselves without a framework is that we need to add our own code to distinguish the methods, e.g.:

```java
        server.createContext("/api/hello", (exchange -> {

            if ("GET".equals(exchange.getRequestMethod())) {
                String respText = "Hello!";
                exchange.sendResponseHeaders(200, respText.getBytes().length);
                OutputStream output = exchange.getResponseBody();
                output.write(respText.getBytes());
                output.flush();
            } else {
                exchange.sendResponseHeaders(405, -1);// 405 Method Not Allowed
            }
            exchange.close();
        }));
```

Now try again request: 
```bash
curl -v -X POST localhost:8000/api/hello
```
and the response would be like: 

```bash
> POST /api/hello HTTP/1.1
> Host: localhost:8000
> User-Agent: curl/7.61.0
> Accept: */*
> 
< HTTP/1.1 405 Method Not Allowed
```

There are also a few things to remember, like to flush output or close exchange every time we return from the api.
When I used Spring I even did not have to think about it.

Try this part from [step-3](https://medium.com/r/?url=https%3A%2F%2Fgithub.com%2Fpiczmar%2Fpure-java-rest-api%2Ftree%2Fstep-3) branch.

## Parsing request params
Parsing request params is another "feature" which we'll need to implement ourselves in contrary to utilising a framework.
Let's say we would like our hello api to respond with a name passed as a param, e.g.: 

```bash
curl localhost:8000/api/hello?name=Marcin

Hello Marcin!

```
We could parse params with a method like: 

```java
public static Map<String, List<String>> splitQuery(String query) {
        if (query == null || "".equals(query)) {
            return Collections.emptyMap();
        }

        return Pattern.compile("&").splitAsStream(query)
            .map(s -> Arrays.copyOf(s.split("="), 2))
            .collect(groupingBy(s -> decode(s[0]), mapping(s -> decode(s[1]), toList())));

    }
```

and use it as below: 

```java
 Map<String, List<String>> params = splitQuery(exchange.getRequestURI().getRawQuery());
String noNameText = "Anonymous";
String name = params.getOrDefault("name", List.of(noNameText)).stream().findFirst().orElse(noNameText);
String respText = String.format("Hello %s!", name);
           
```

You can find complete example in [step-4](https://medium.com/r/?url=https%3A%2F%2Fgithub.com%2Fpiczmar%2Fpure-java-rest-api%2Ftree%2Fstep-4) branch.

Similarly if we wanted to use path params, e.g.: 

```bash
curl localhost:8000/api/items/1
```
to get item by id=1, we would need to parse the path ourselves to extract an id from it. This is getting cumbersome.


## Secure endpoint
A common case in each REST API is to protect some endpoints with credentials, e.g. using basic authentication.
For each server context we can set an authenticator as below: 

```java
HttpContext context =server.createContext("/api/hello", (exchange -> {
  // this part remains unchanged
}));
context.setAuthenticator(new BasicAuthenticator("myrealm") {
    @Override
    public boolean checkCredentials(String user, String pwd) {
        return user.equals("admin") && pwd.equals("admin");
    }
});
```

The "myrealm" in `BasicAuthenticator` is a realm name. Realm is a virtual name which can be used to separate different authentication spaces. 
You can read more about it in [RFC 1945](https://tools.ietf.org/html/rfc1945#section-11)

You can now invoke this protected endpoint by adding an `Authorization` header like that: 

```bash
curl -v localhost:8000/api/hello?name=Marcin -H 'Authorization: Basic YWRtaW46YWRtaW4='
```

The text after `Basic` is a Base64 encoded `admin:admin`  which are credentials hardcoded in our example code.
In real application to authenticate user you would probably get it from the header and compare with username and password store in database.
If you skip the header the API will respond with status
```
HTTP/1.1 401 Unauthorized

```

Check out the complete code from [step-5](https://medium.com/r/?url=https%3A%2F%2Fgithub.com%2Fpiczmar%2Fpure-java-rest-api%2Ftree%2Fstep-5) branch.


## JSON, exception handlers and others

Now it's time for more complex example. 

From my past experience in software development the most common API I was developing was exchanging JSON.

We're going to develop an API to register new users. We will use an in-memory database to store them.

Our user domain object will be simple: 

```java
@Value
@Builder
public class User {

    String id;
    String login;
    String password;
}

```
I'm using Lombok annotations to save me from constructor and getters boilerplate code, it will be generated in build time.

In REST API I want to pass only login and password so I created a separate domain object: 

```java
@Value
@Builder
public class NewUser {

    String login;
    String password;
}

```

Users will be created in a service which I will use in my API handler. The service method is simply storing the user. 
In complete application it could do more, like send events after successful user registration.

```java
public String create(NewUser user) {
    return userRepository.create(user);
}
```

Our in-memory implementation of repository is as follows: 
```java

import java.util.Map;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;

import com.consulner.domain.user.NewUser;
import com.consulner.domain.user.User;
import com.consulner.domain.user.UserRepository;

public class InMemoryUserRepository implements UserRepository {

    private static final Map USERS_STORE = new ConcurrentHashMap();

    @Override
    public String create(NewUser newUser) {
        String id = UUID.randomUUID().toString();
        User user = User.builder()
            .id(id)
            .login(newUser.getLogin())
            .password(newUser.getPassword())
            .build();
        USERS_STORE.put(newUser.getLogin(), user);

        return id;
    }
}
```
Finally, let's glue all together in handler:

```java
protected void handle(HttpExchange exchange) throws IOException {
        if (!exchange.getRequestMethod().equals("POST")) {
            throw new UnsupportedOperationException();
        }

        RegistrationRequest registerRequest = readRequest(exchange.getRequestBody(), RegistrationRequest.class);

        NewUser user = NewUser.builder()
            .login(registerRequest.getLogin())
            .password(PasswordEncoder.encode(registerRequest.getPassword()))
            .build();

        String userId = userService.create(user);

        exchange.getResponseHeaders().set(Constants.CONTENT_TYPE, Constants.APPLICATION_JSON);
        exchange.sendResponseHeaders(StatusCode.CREATED.getCode(), 0);

        byte[] response = writeResponse(new RegistrationResponse(userId));

        OutputStream responseBody = exchange.getResponseBody();
        responseBody.write(response);
        responseBody.close();
    }
```

It translates JSON request into `RegistrationRequest` object: 

```java
@Value
class RegistrationRequest {

    String login;
    String password;
}
```

which I later map to domain object `NewUser` to finally save it in database and write response as JSON.

I need to translate `RegistrationResponse` object back to JSON string.

Marshalling and unmarshalling JSON is done with Jackson object mapper (`com.fasterxml.jackson.databind.ObjectMapper`).

And this is how I instantiate the new handler in application main method: 

```java
 public static void main(String[] args) throws IOException {
        int serverPort = 8000;
        HttpServer server = HttpServer.create(new InetSocketAddress(serverPort), 0);

        RegistrationHandler registrationHandler = new RegistrationHandler(getUserService(), getObjectMapper(),
            getErrorHandler());
        server.createContext("/api/users/register", registrationHandler::handle);
        
        // here follows the rest.. 

 }
```

You can find the working example in [step-6](https://medium.com/r/?url=https%3A%2F%2Fgithub.com%2Fpiczmar%2Fpure-java-rest-api%2Ftree%2Fstep-6) git branch, where I also added a global exception handler which is used
by the API to respond with a standard JSON error message in case, e.g. when HTTP method is not supported or API request is malformed.


You can run the application and try one of the example requests below: 

```bash
curl -X POST localhost:8000/api/users/register -d '{"login": "test" , "password" : "test"}'
```

response: 
```bash
{"id":"395eab24-1fdd-41ae-b47e-302591e6127e"}
```

```bash
curl -v -X POST localhost:8000/api/users/register -d '{"wrong": "request"}'
```

response: 
```bash
< HTTP/1.1 400 Bad Request
< Date: Sat, 29 Dec 2018 00:11:21 GMT
< Transfer-encoding: chunked
< Content-type: application/json
< 
* Connection #0 to host localhost left intact
{"code":400,"message":"Unrecognized field \"wrong\" (class com.consulner.app.api.user.RegistrationRequest), not marked as ignorable (2 known properties: \"login\", \"password\"])\n at [Source: (sun.net.httpserver.FixedLengthInputStream); line: 1, column: 21] (through reference chain: com.consulner.app.api.user.RegistrationRequest[\"wrong\"])"}
```

Also, by chance I encountered a project [java-express](https://github.com/Simonwep/java-express) 
which is a Java counterpart of Node.js [Express](https://expressjs.com/) framework 
and is using jdk.httpserver as well, so all the concepts covered in this article you can find in real-life application framework :) 
which is also small enough to digest the codes quickly.