{title:'Overview', created:'9.0.0'}

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:

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 {@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:

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...