REST Server Overview

A REST resource is simply a Java class annotated with @Rest. The most common case is a class that extends BasicRestServlet, which itself is simply an extension of HttpServlet which allows it to be deployed as a servlet.

Juneau has two sample applications for demonstrating how to use the REST API, one using Jetty and one using Spring Boot:

org.apache.juneau.examples.rest.jettyorg.apache.juneau.examples.rest.springboot

The org.apache.juneau.examples.rest.springboot application is described in the section SpringBoot Overview.

The Jetty application consists of the following application class that registers our top-level servlet:

public class App {

    public static void main(String[] args) throws Exception {
        JettyMicroservice
            .create()
            .args(args)
            .servlet(RootResources.class)
            .build()
            .start()
            .startConsole()
            .join();
    }
}

The root resources class is an example of a router page that is used to attach children to:

@Rest(
    title="Root resources",
    description="Example of a router resource page.",
    children={
        HelloWorldResource.class,
        DtoExamples.class,
        UtilityBeansResource.class,
        HtmlBeansResource.class,
        ConfigResource.class,
        ShutdownResource.class
    }
)
@HtmlDocConfig(
    widgets={
        ContentTypeMenuItem.class
    },
    navlinks={
        "api: servlet:/api",
        "stats: servlet:/stats",
        "$W{ContentTypeMenuItem}",
        "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/RootResources.java"
    },
    aside={
        "<div class='text'>",
        "    <p>This is an example of a 'router' page that serves as a jumping-off point to child resources.</p>",
        "    <p>Resources can be nested arbitrarily deep through router pages.</p>",
        "    <p>Note the <span class='link'>API</span> link provided that lets you see the generated swagger doc for this page.</p>",
        "    <p>Also note the <span class='link'>STATS</span> link to view runtime statistics on this page.</p>",
        "    <p>Also note the <span class='link'>SOURCE</span> link to view the source code for the page.</p>",
        "    <p>All content on pages in the UI are serialized POJOs.  In this case, it's a serialized array of beans with 2 properties, 'name' and 'description'.</p>",
        "    <p>Other features (such as this aside) are added through annotations.</p>",
        "</div>"
    },
    asideFloat="RIGHT"
)
@SerializerConfig(
    // For testing purposes, we want to use single quotes in all the serializers so it's easier to do simple
    // String comparisons.
    // You can apply any of the Serializer/Parser/BeanContext settings this way.
    quoteChar="'"
)
public class RootResources extends BasicRestServletGroup {
    private static final long serialVersionUID = 1L;
}

This is what it looks like in a browser:

HTML representation

JSON representation

The HelloWorldResource class is our basic example of a child REST resource:

@Rest(
    title="Hello World",
    description="An example of the simplest-possible resource",
    path="/helloWorld"
)
@HtmlDocConfig(
    aside={
        "<div style='max-width:400px' class='text'>",
        "    <p>This page shows a resource that simply response with a 'Hello world!' message</p>",
        "    <p>The POJO serialized is a simple String.</p>",
        "</div>"
    }
)
public class HelloWorldResource extends BasicRestObject {

    @RestGet(path="/*", summary="Responds with \"Hello world!\"")
    public String sayHello() {
        return "Hello world!";
    }
}

This is what it looks like in a browser:

HTML representation

It doesn't much simpler than that. In this case, we're simply returning a string that will be converted to any of the supported languages (e.g. JSON, XML, HTML, ...). However, we could have returned any POJO consisting of beans, Maps, Collections, etc...