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.

Related Documentation

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