Bare-Metal REST with just a few lines of code

Bare-Metal REST with just a few lines of code

Find out about an alternative approach on how you can implement a serverless, tiny and slim RESTful service or a tiny and slim REST client with a little help from Java’s lambda expressions. Moreover, we skip using Heavy-Weight frameworks doing magic in the background. Instead we will follow the classic Bare-Metal approach where you stay in full control of your application’s lifecycle.

”… Bare-Metal programming is a term for programming that operates without various layers of abstraction or, as some experts describe it, without an operating system supporting it … “ (see Bare-Metal programming).

(in this context I use the term Bare-Metal for programming that operates without various layers of abstraction regarding the Java ecosystem)

A while ago I was thinking on what became of good old imperative object orientated Java programming:

There came generics, keeping your code comprehensible and more reliable, which is a good thing. There came lambda expressions and with it more functional programming, still keeping your code comprehensible, still being a good thing. Meanwhile there came the Heavy-Weight frameworks doing all kinds of magic in the background: Scanning your classpath, introspecting your bytecode, making decisions not easily traceable by you, the programmer, taking over your application’s lifecycle, placing you, the programmer, under disability.

Do we really need full blown lifecycle management and web container support in a Microservices and IoT world?


What I actually want to do when programming is to keep control:

I want to instantiate some class with which I can do REST requests. I want to instantiate some class with which I can do RESTful services. I don’t want to buy classpath scanning or bytecode introspection only for doing REST. I want to do Bare-Metal programming instead of programming in a steel-boned corset of some application server or Heavy-Weight framework

… and the refcodes-rest artifact is just one piece in the puzzle of doing so. For example open up as many HTTP/HTTPS ports for as many different lambdas in a single serverless RESTful service as you wish.

(you may skip the below Bare-Metal section in case you want to dive directly into the refcodes-rest programming)


In comparison to the Heavy-Weight frameworks, Bare-Metal (and therewith the refcodes-rest artifact) follows an opposite approach: Give the programmer back the control.

Bare-Metal programming is the kinda programming where you decide on how your application is constructed, where you control the lifecycle and where you create a damn simple listener for processing a resource’s REST request instead of spreading tons of framework specific annotations over your code, interpreted magically by a framework at runtime.

Just to get an impression on the overhead your applications are carrying around: Using Spring Boot, just to get a RESTful service up-and-running, your archive including all required libraries gets about 13 MB of size. Moreover, Spring Boot takes over full control of your application’s lifecycle. No Bare-Metal anymore.

In comparison, the Bare-Metal approach using the refcodes-rest artifact would fit on three 3.5 inch floppy disks and still keep you in full control of your application’s lifecycle (even including a full blown Bare-Metal refcodes-console command line args parser).

(a + represents 1 MB in the table below)

Stack Size (MB) Bare-Metal
Spring Boot +++++++++++++ No, placing the programmer under disability
refcodes-rest +++ Yes, programmer keeps full control

I admit, the above is a very one-sided, selective and exaggerated comparison of two very different things. The point I am investigating here is the question whether it would be more sufficient to use Bare-Metal straight forward imperative programming paradigms instead of Heavy-Weight frameworks because our services’ complexity is continuously shrinking? Just to mention the Microservices hype and tiny IoT devices being everywhere. Therefore I implemented a Bare-Metal API for doing client side REST requests and for implementing tiny RESTful servers.

Getting started

To get up and running, include the following dependency (without the three dots “…”) in your pom.xml:

1 <dependencies>
2   ...
3   <dependency>
4     <artifactId>refcodes-rest</artifactId>
5     <groupId>org.refcodes</groupId>
6     <version>1.2.5</version>
7   </dependency>
8   ...
9 </dependencies>

For tweaking your configuration such as binding to SLF4J, see the refcodes-rest blog post.

The RESTful server

The TinyRestfulServer demo application uses syntactic sugar for setting up a RESTful server including command line arguments parsing. Basically it requires these three steps to get your RESTful server up and running:

  1. Instantiate the RESTful server
  2. Register your lambda expressions
  3. Start the RESTful server
 1 ...
 2 public static void main( String[] args ) {
 3   // STEP 1: We instantiate our HttpRestServer:
 4   HttpRestServer theRestServer = new HttpRestServerImpl();
 5   // STEP 2: We register our lambda expression:
 6   theRestServer.onGet( "/say/${name}=*", ( aRequest, aResponse ) -> {
 7     String name = aRequest.getWildcardReplacement( "name" );
 8     aResponse.getHeaderFields().withContentType( MediaType.APPLICATION_JSON ).withAddCookie( "greeting", "Hello " + name + "!" );
 9     return "Hello " + name + "!" ;
10   } ).open();
11   // STEP 3: We open the HttpRestServer instance on port 8080:
12 8080 );
13 }
14 ...

The above example registers to the the imaginary resource “/say” and provides you with the addressed element (“name”). You may produce a response including cookies and required Header-Fields via the provided lambda expression.

Under the hood

The diagram illustrates the interaction between a client A, the server B and the business part C:

  • A: The client such as a browser or the HttpRestClient issuing a HTTP-Request
  • B: The HttpRestServer receiving the HTTP-Request
  • C: Your RestEndpoint processing the HTTP-Request and producing a response

HttpRestServer interaction with a client

  1. The client issues a HTTP-Request with a given HttpMethod (GET, POST, PUT or DELETE)
  2. The HttpRestServer analyzes the request and dispatches it to the according RestEndpoint
  3. Its HttpMethod must match and the Locator-Pattern must match the Locator
  4. The lambda of the matching RestEndpoint is invoked and produces a response
  5. The HttpRestServer marshals the response and sends it back to the client
  6. The client receives the HTTP-Response as produced by your lambda

The REST client

Basically it requires these three steps for firing a REST request from within your client:

  1. Instantiate the REST client
  2. Register your lambda expression for the response
  3. Fire the client’s REST request
 1 ...
 2 public static void main( String[] args ) {
 3   // STEP 1: We instantiate our HttpRestClient:
 4   HttpRestClient theRestClient = new HttpRestClientImpl();
 5   // STEP 2: We register our lambda expression:
 6   theRestClient.doRequest( HttpMethod.POST, "http://mydomain:8080/say/nolan", ( aResponse ) -> {
 7     String theResponse = aResponse.getResponse( String.class );
 8   } ).withRequest( ... ).open();
 9   // STEP 3: We opened the caller so it fires the request to port 8080 of domain "mydomain"
10 }
11 ...

The above example issues a POST request to some imaginary “/say” resource, addressing the element “nolan” and with some request body (any Object which can be marshaled with the according Content-Type) and processes the response asynchronously via the provided lambda expression.

Under the hood

The diagram illustrates the interaction between the business part A, the client B and a server C:

  • A: Your RestCaller producing the HTTP-Request and processing the response
  • B: The HttpRestClient sending the HTTP-Request
  • C: The server such as a the HttpRestServer receiving a HTTP-Request

HttpRestServer interaction with a client

  1. The HTTP-Request of your RestCaller is processed by the HttpRestClient
  2. The HttpRestClient marshals the request and sends it to the server
  3. The server receives the HTTP-Request as produced by your RestCaller
  4. A HTTP-Response is produces by the server and passed back to the HttpRestClient
  5. The HttpRestClient invokes the lambda of the RestCaller with the response
  6. The lambda of the RestCaller is invoked and processes the response

Further reading

For an in depth description of the refcodes-rest artifact on using syntactic sugar or the syntax of the locator patterns ( e.g. "/say/${name}=*" from the above example on RESTful services) please refer to the refcodes-rest blog post. See also the example code at

comments powered by Disqus