Skip to main content

juneau-rest-server Basics

Maven Dependency​

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

Java Library​

juneau-rest-server-0.0.0.jar

OSGi Module​

org.apache.juneau.rest.server_0.0.0.jar

The juneau-rest-server library allows you to quickly wrap POJOs and expose them as full-fledged REST resources served up in a servlet container using a bare-minimum amount of code.

The primary goal for Juneau was to make it as easy as possible to implement easy-to-read and self-documenting REST resources using very little code.

One of the biggest advantages of the Juneau REST framework over similar architectures is that it hides the serialization layer from the developer.

The developer can work entirely with POJOs and let the Juneau framework handle all the serialization and parsing work.

The developer need never know what the Accept or Content-Type or Accept-Encoding (etc...) header values are because those details are all handled by the framework.

The API builds upon the existing JEE Servlet API.

The root class, RestServlet is nothing but a specialized HttpServlet, and the RestRequest and RestResponse classes are nothing more than specialized HttpServletRequest and HttpServletResponse objects.

This allows maximum flexibility for the developer since you can let Juneau handle operations such as serialization, or you can revert to the existing servlet APIs to do low-level processing of requests yourself.

It also means you need nothing more than a Servlet container such as Jetty to use the REST framework.

Contents/Features​

  • Deployable in standard Servlet containers.
  • Deployable in Spring Boot environments with full support for injected beans.
  • Serializes POJOs to JSON, XML, HTML, URL-Encoding, UON, RDF/XML, N-Triple, Turtle, N3, SOAP, or Java-serialized-object based on value of Accept header. No user code is required to handle these types.
    • Extensible design that provides ability to override existing content type handlers, or add the ability to handle other kinds of content types.
  • Parses content of POST/PUT request bodies to POJOs.
  • Automatic built-in ability to serialize POJO metadata to JSON+SCHEMA, XML+SCHEMA, or HTML+SCHEMA based on Accept header.
  • Automatic negotiation of output Writer based on HTTP headers.
    • Automatic handling of Accept-Charset header for all character sets supported by the JVM.
    • Automatic handling of Accept-Encoding header with registered encoders.
  • Automatic error handling.
    • Automatic 401 errors (Unauthorized) on failed guards.
    • Automatic 404 errors (Not Found) on unmatched path patterns.
    • Automatic 405 errors (Method Not Implemented) on unimplemented methods.
    • Automatic 406 errors (Not Acceptable) when no matching serializer was found to handle the Accept header.
    • Automatic 412 errors (Precondition Failed) when all matchers failed to match.
    • Automatic 415 errors (Unsupported Media Type) when no matching parser was found was found to handle the Content-Type header.
    • Automatic 500 errors on uncaught exceptions.
  • Support for parsing all HTTP parts (headers, query, formData, path variables) using Swagger formatting rules and validations. Not limited to simple POJOs but rather you can represent arbitrarily-complex POJOs in any HTTP part using UON notation.
  • Auto-created Swagger JSON and Swagger UI available through OPTIONS requests of resources.
  • Various useful debugging features that make debugging using a browser extremely simple...
    • Ability to pass HTTP header values as URL GET parameters (e.g. &Accept=text/xml).
    • Ability to pass HTTP content on PUT/POST requests as a URL GET parameter (e.g. &content=(foo=bar)).
    • Ability to simulate non-GET requests using a &method GET parameter (e.g. &method=POST).
    • Ability to force text/plain on response using GET parameter &plainText=true.
  • Ability to implement overloaded HTTP methods through the use of the &method attribute (e.g. &method=FOO).
  • Ability to match URL patterns (e.g. /foo/{fooId}/bar/{barId}) against URLs (e.g. /foo/123/bar/456/bing).
  • Ability to associate guards at the resource or method levels through annotations. Typically useful for security but can be used for a variety of purposes.
  • Ability to associate converters at the resource or method levels through annotations. Typically useful for performing conversions on input and output, such as for supporting older input and output formats.

Many of the examples in this document are pulled directly from juneau-examples-rest.