Skip to main content

juneau-examples-rest

The juneau-examples-rest module provides comprehensive examples demonstrating how to build REST APIs using Apache Juneau's REST server capabilities.

Overview​

This module showcases practical examples of building REST services with Juneau, including:

  • REST resource implementation
  • HTTP method handling
  • Request/response serialization
  • Error handling and validation
  • Integration with various data sources

Getting Started​

To use the examples in this module, add the following dependencies to your project:

<dependency>
    <groupId>org.apache.juneau</groupId>
    <artifactId>juneau-rest-server</artifactId>
    <version>${juneau.version}</version>
</dependency>
<dependency>
    <groupId>org.apache.juneau</groupId>
    <artifactId>juneau-rest-client</artifactId>
    <version>${juneau.version}</version>
</dependency>

Example Resources​

HelloWorldResource.java​

A simple REST resource demonstrating basic HTTP method handling and response serialization.

Features:

  • GET method implementation
  • JSON response serialization
  • Simple POJO return types
  • Basic error handling

RequestEchoResource.java​

Shows how to handle incoming requests and echo back request information.

Features:

  • Request object inspection
  • Header and parameter access
  • Request body parsing
  • Response customization

PhotosResource.java​

Demonstrates file handling and binary data management in REST APIs.

Features:

  • File upload handling
  • Binary data processing
  • Image metadata extraction
  • File serving capabilities

DTO Bean Examples​

AtomFeedResource.java​

Shows how to create and serve Atom feeds using Juneau's DTO bean capabilities.

Features:

  • Atom feed generation
  • RSS/Atom standard compliance
  • Dynamic content updates
  • Feed metadata management

JsonSchemaResource.java​

Demonstrates JSON Schema generation for API documentation and validation.

Features:

  • Automatic schema generation
  • API documentation
  • Request/response validation
  • Schema customization

Command Pattern Examples​

EchoCommand.java​

Illustrates the command pattern implementation for REST operations.

Features:

  • Command object design
  • Parameter validation
  • Result processing
  • Error handling

Advanced Features​

AdminGuard​

Demonstrates security and access control in REST APIs.

Features:

  • Authentication checking
  • Authorization validation
  • Security context handling
  • Access control patterns

UtilityBeansResource.java​

Shows how to create utility resources for common operations.

Features:

  • Utility method exposure
  • Common operation patterns
  • Reusable functionality
  • Service composition

HtmlBeansResource.java​

Demonstrates HTML generation and web interface creation.

Features:

  • HTML response generation
  • Template-based rendering
  • Web interface creation
  • Form handling

Project Structure​

The examples are organized in a clear package structure:

org.apache.juneau.examples.rest/
├── HelloWorldResource.java
├── RequestEchoResource.java
├── PhotosResource.java
├── AdminGuard.java
├── UtilityBeansResource.java
├── HtmlBeansResource.java
├── command/
│   └── EchoCommand.java
└── dto/
    ├── AtomFeedResource.java
    ├── JsonSchemaResource.java
    └── DtoExamples.java

Configuration Examples​

Basic REST Configuration​

@Rest(
    path="/api",
    serializers={JsonSerializer.class, XmlSerializer.class},
    parsers={JsonParser.class, XmlParser.class}
)
public class MyResource {
    // Resource implementation
}

Advanced Configuration​

@Rest(
    path="/api/v1",
    serializers={JsonSerializer.class, XmlSerializer.class, HtmlSerializer.class},
    parsers={JsonParser.class, XmlParser.class, HtmlParser.class},
    config={
        @RestConfig(name="REST_allowMethodParam", value="true"),
        @RestConfig(name="REST_allowHeaderParam", value="true")
    }
)
public class AdvancedResource {
    // Advanced resource implementation
}

Testing the Examples​

Running Individual Examples​

Each resource can be tested independently by deploying it to a servlet container or using the embedded Jetty server.

Integration Testing​

The module includes integration tests that demonstrate:

  • End-to-end request/response cycles
  • Error scenario handling
  • Performance characteristics
  • Cross-browser compatibility

Best Practices Demonstrated​

Resource Design​

  • Single responsibility principle
  • Clear method naming
  • Consistent error handling
  • Proper HTTP status codes

Data Handling​

  • Input validation
  • Output formatting
  • Error serialization
  • Content type negotiation

Security​

  • Authentication patterns
  • Authorization checks
  • Input sanitization
  • Output filtering

Integration with Other Modules​

These REST examples integrate with:

juneau-examples-core - Uses core serialization examplesjuneau-petstore - Provides foundation for complete applicationjuneau-microservice - Demonstrates microservice patterns

Deployment Options​

Servlet Container​

Deploy to any Servlet 3.1+ container:

  • Tomcat
  • Jetty
  • WildFly
  • WebLogic

Spring Boot Integration​

Use with Spring Boot for rapid development:

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Embedded Server​

Run as standalone application with embedded server.

Juneau REST Server Basics - Core REST server conceptsJuneau REST Client Basics - REST client usagejuneau-examples-core - Core serialization examplesjuneau-petstore - Complete application example

Source Code​

The complete source code for all REST examples is available in the juneau-examples-rest module of the Apache Juneau project.

Contributing​

To contribute new REST examples:

  1. Follow RESTful design principles
  2. Include comprehensive error handling
  3. Provide clear documentation
  4. Test with various HTTP clients
  5. Update this documentation when adding new examples