A REST resource is simply a Java class annotated with {@link oajr.annotation.Rest @Rest}.
The most common case is a class that extends {@link oajr.servlet.BasicRestServlet}, which itself is simply an
extension of {@link jakarta.servlet.http.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.jetty
- org.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:
The {@link oaj.examples.rest.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:
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...