@Rest and @RestOp

This page is a consolidated reference for the attributes of the three annotations that configure a REST resource:

• @Rest - class-level configuration of a resource.
• @RestOp and its verb-specific variants (@RestGet, @RestPut, @RestPost, @RestDelete, @RestPatch, @RestOptions) - per-method configuration.
• @Mixin - a rich mixin declaration used inside @Rest(mixinDefs=...).

All three live in the org.apache.juneau.rest.server package of the juneau-rest-server module. @Rest is applied to classes (@Target(TYPE)); @RestOp and the verb annotations are applied to methods (@Target(METHOD)); all are @Inherited. @Mixin has an empty @Target and can only be used as a value of @Rest(mixinDefs).

Unless stated otherwise, string attributes support SVL variables. Tri-state attributes are strings taking "true", "false" or "" (the default, meaning "inherit from the enclosing level").

@Rest attributes

Identity, mounting and composition

Attribute	Type	Description
path	String	Resource path. Child-to-parent search. Only effective when the class is registered directly as a top-level resource; when the class is a mixin the host's path governs. See Path Variables.
paths	String[]	Additional top-level mount paths. Each element is SVL-resolved and then comma-split.
children	Class<?>[]	Child resources, each mounted under its own URL subtree. See Child Resources.
childrenDefs	Child[]	Rich child definitions (host-side seed form of children).
mixins	Class<?>[]	Operation-provider classes whose @RestOp methods are composed into this resource. See Mixin Sub-Contexts.
mixinDefs	Mixin[]	Rich mixin definitions with host-side overrides. See @Mixin attributes below.
mergeResponseProcessorsIntoHost	boolean	Mixin-declared opt-in: when this class is composed as a mixin via a plain mixins= reference, fold its own responseProcessors into the host's chain. Default false.
lazyChildren	String	Opt the parent into deferred (first-invocation) construction of its children.
eagerInit	String	Eagerly initialize framework-managed memoizers during RestContext construction.
config	String	Location of the configuration file. The keyword SYSTEM_DEFAULT refers to Config.getSystemDefault(). See Configuration Files.
messages	String	Location of the resource bundle for this class.
staticFiles	Class<? extends StaticFiles>	Static-file provider. Default StaticFiles.Void.class.
authenticator	Class<? extends RestAuthenticator>	Resource-level authenticator. Default RestAuthenticator.Null.class. See Authenticator.

Marshalling and content negotiation

Attribute	Type	Description
serializers	Class<? extends Serializer>[]	Serializers for response bodies.
parsers	Class<?>[]	Parsers for request bodies.
encoders	Class<? extends Encoder>[]	Compression encoders (e.g. gzip). See Encoders.
converters	Class<? extends RestConverter>[]	Class-level response converters.
produces	String[]	Supported Accept media types, overriding those inferred from the serializers.
consumes	String[]	Supported Content-Type media types, overriding those inferred from the parsers.
partSerializer	Class<? extends HttpPartSerializer>	Part serializer for headers, query/form parameters and URI parts. Default HttpPartSerializer.Void.class.
partParser	Class<? extends HttpPartParser>	Part parser for headers, query/form parameters and URI parts. Default HttpPartParser.Void.class.
defaultAccept	String	Default Accept header when not on the request.
defaultContentType	String	Default Content-Type header when not on the request.
defaultCharset	String	Default character encoding when not on the request.
maxInput	String	Maximum allowed request input size, in bytes.
allowedSerializerOptions	String[]	Serializer session option keys that clients are allowed to set. See Session Options.
allowedParserOptions	String[]	Parser session option keys that clients are allowed to set. See Session Options.
debugMarshalling	String	Tri-state opt-in to REST-driven serializer/parser debug behavior.

Defaults and request parameters

Attribute	Type	Description
defaultRequestHeaders	String[]	Default request headers used when not sent by the client.
defaultRequestAttributes	String[]	Default request attributes used when not already set.
defaultResponseHeaders	String[]	Default response headers used when not set by the method.
headerParams	Header[]	Default definitions for @Header method parameters across the class.
queryParams	Query[]	Default definitions for @Query method parameters across the class.
formDataParams	FormData[]	Default definitions for @FormData method parameters across the class.
pathParams	Path[]	Default definitions for @Path method parameters across the class.
allowedHeaderParams	String	Headers (e.g. Accept, Content-Type) that may be passed as URL query parameters.
allowedMethodParams	String	HTTP methods that may be requested through a method URL parameter. "*" means all. On a safe request (GET, HEAD, OPTIONS, TRACE) an admitted method is honored only if it is safe or its operation is declared read=true; otherwise the request is refused with 405. See Overloading HTTP Methods.
allowedMethodHeaders	String	HTTP methods that may be requested through an X-Method, X-HTTP-Method-Override, X-HTTP-Method or X-Method-Override header. "*" means all. Empty (off) by default. Conflicting overrides are refused with 400. The same safe-request rule as allowedMethodParams applies. See Overloading HTTP Methods.
disableContentParam	String	Set to true to disable the content URL parameter on PUT and POST requests.
clientVersionHeader	String	Name of the header carrying the client version (see @RestOp(clientVersion)).

For the allowed*Params/allowedMethodHeaders attributes, the value "NONE" (case-insensitive) suppresses inheriting a value from a parent class.

Processing pipeline, security and runtime

Attribute	Type	Description
guards	Class<? extends RestGuard>[]	Guards applied to all operations of the class. See Guards.
roleGuard	String	Role expression required to access operations, e.g. "ROLE_ADMIN".
rolesDeclared	String	Comma-delimited list of all possible user roles.
responseProcessors	Class<? extends ResponseProcessor>[]	Processors that convert returned POJOs into HTTP responses.
restOpArgs	Class<? extends RestOpArg>[]	Additional Java method parameter resolvers. See Java Method Parameters.
problemDetails	String	Tri-state opt-in to RFC 7807 / RFC 9457 application/problem+json error responses. See Problem Details.
renderResponseStackTraces	String	Render stack traces in HTTP response bodies when errors occur.
virtualThreads	String	Tri-state opt-in to per-request virtual-thread dispatch (Java 21+; silently ignored with a warning on older JVMs).
asyncTimeoutMillis	String	Timeout for CompletableFuture-returning handlers. Default 30,000 ms; "0" disables. On timeout the response is 504 Gateway Timeout. See Async Dispatch.
asyncCompletionExecutor	String	Name of the Executor bean on which CompletableFuture completion callbacks are run.
observability	String	Per-resource observability opt-in/opt-out. See Observability.
noInherit	String[]	Property names for which less-derived contributions are not inherited (see below).

Documentation and URI resolution

Attribute	Type	Description
title	String[]	Servlet title; populates the Swagger title.
description	String[]	Servlet description; populates the Swagger description.
siteName	String	Site name applied to the entire site.
swagger	Swagger	Swagger metadata (which uses @Contact, @License, @Tag; see Annotations).
swaggerProvider	Class<? extends SwaggerProvider>	Swagger provider. Default SwaggerProvider.Void.class.
openApiProvider	Class<? extends OpenApiProvider>	OpenAPI 3.1 provider. Default OpenApiProvider.Void.class.
uriAuthority	String	Overrides the authority path for this resource and its children.
uriContext	String	Overrides the context path for this resource and its children.
uriRelativity	String	How relative URIs are interpreted by serializers.
uriResolution	String	How relative URIs are resolved by serializers.

noInherit tokens

On @Rest, accepted values are allowedParserOptions, allowedSerializerOptions, allowedHeaderParams, allowedMethodHeaders, allowedMethodParams, disableContentParam, renderResponseStackTraces, problemDetails, debugMarshalling, eagerInit, lazyChildren, clientVersionHeader, uriAuthority, uriContext, uriRelativity and uriResolution. On a class used as a mixin, the token set additionally includes serializers, parsers, encoders, converters, responseProcessors, restOpArgs, guards, partSerializer, partParser and messages, and blocks the host-to-mixin inheritance walk for that property. The noInherit attribute itself is never inherited.

@RestOp and verb-annotation attributes

@RestOp is the general form. The verb annotations fix the HTTP method and therefore do not have a method attribute. Their value attribute is a path-only shorthand, whereas @RestOp(value) takes the combined "METHOD /path" form.

Example

// All equivalent:
@RestOp(method="PUT", path="/{propertyName}")
@RestOp("PUT /{propertyName}")
@RestPut("/{propertyName}")
@RestPut(path="/{propertyName}")

Attributes available on every operation annotation

@RestOp, @RestGet, @RestPut, @RestPost, @RestDelete, @RestPatch and @RestOptions all provide:

Attribute	Type	Description
value	String	Shorthand: "METHOD /path" on @RestOp, path only on the verb annotations.
path	String[]	Path pattern(s). See Path Patterns.
clientVersion	String	Client version range (e.g. "[0,1.0)", "1.0") matched against @Rest(clientVersionHeader).
guards	Class<? extends RestGuard>[]	Guards for this operation.
roleGuard	String	Role expression for this operation.
rolesDeclared	String	Declared roles.
encoders	Class<? extends Encoder>[]	Compression encoders.
defaultAccept	String	Default Accept header.
defaultCharset	String	Default character encoding.
defaultRequestAttributes	String[]	Default request attributes.
defaultRequestHeaders	String[]	Default request headers.
defaultResponseHeaders	String[]	Default response headers.
allowedSerializerOptions	String[]	Allowed serializer session option keys.
allowedParserOptions	String[]	Allowed parser session option keys.
noInherit	String[]	Properties not inherited from @Rest. On operations the accepted values are allowedSerializerOptions, allowedParserOptions, problemDetails and debugMarshalling.
problemDetails	String	Tri-state override of @Rest(problemDetails).
debugMarshalling	String	Tri-state override of @Rest(debugMarshalling).
observability	String	Tri-state override of @Rest(observability).
asyncCompletionExecutor	String	Executor bean name for async completion.
description	String[]	Swagger operation description.
swagger	OpSwagger	Swagger operation metadata.
matchers	Class<? extends RestMatcher>[]	RestMatcher classes that let several Java methods share a method and path. See Matchers.
summary	String	Swagger operation summary.
defaultRequestQueryData	String[]	Default query parameters used when not sent by the client.
metricName, metricTags	String	Name and tags for the metrics recorded for this operation.

Availability of the remaining attributes

A Y means the attribute is declared on that annotation (derived directly from the annotation sources).

Attribute	@RestOp	@RestGet	@RestPut	@RestPost	@RestDelete	@RestPatch	@RestOptions
method	Y	-	-	-	-	-	-
serializers	Y	Y	Y	Y	-	Y	Y
converters	Y	Y	Y	Y	-	Y	Y
produces	Y	Y	Y	Y	-	Y	Y
parsers	Y	-	Y	Y	-	Y	-
consumes	Y	-	Y	Y	-	Y	-
maxInput	Y	-	Y	Y	-	Y	-
defaultContentType	Y	-	Y	Y	-	Y	-
defaultRequestFormData	Y	-	Y	Y	-	Y	-
virtualThreads	Y	-	-	-	-	-	-
asyncTimeoutMillis	Y	-	-	-	-	-	-

Reading the matrix: body-consuming attributes (parsers, consumes, maxInput, defaultContentType, defaultRequestFormData) are not available on @RestGet, @RestDelete or @RestOptions; response-shaping attributes (serializers, converters, produces) are not available on @RestDelete. virtualThreads and asyncTimeoutMillis can currently only be set per-operation on the general @RestOp annotation (both can also be set resource-wide on @Rest).

Operation-specific attributes

Attribute	Description
method	The HTTP method name. Besides the standard names: "*" matches any method (use @Method or RestRequest.getMethod() to tell them apart); "" auto-detects from the Java method name (defaulting to GET); "RRPC" marks a remote-proxy interface method; any other value is an overloaded method selected with the &method= URL parameter (on a safe request, only when read=true). See Inferred HTTP Methods and Paths and Overloading HTTP Methods.
read	Declares that a custom method only reads, so an override on a safe request (GET ?method=VIEW) may reach it. Accepted only on custom methods: POST, PUT, PATCH, DELETE, CONNECT, "*", "RRPC" or @Mutating fail at startup. See Overloading HTTP Methods.
virtualThreads	Tri-state override of @Rest(virtualThreads).
asyncTimeoutMillis	Override of @Rest(asyncTimeoutMillis).

@Mixin attributes

@Mixin is used only inside @Rest(mixinDefs=...). It names a mixin class and lets the host override selected @Rest-level settings for that mixin's endpoints without editing the mixin class.

Example

@Rest(
    mixinDefs=@Mixin(type=FooMixin.class, guards=AdminGuard.class)
)
public class MyResource extends BasicRestServlet { ... }

Attribute	Type	Description
type	Class<?>	Required. The mixin class to compose into the host.
mergeIntoHost	boolean	Opt-in (default false): additionally append the mixin's own list-shaped @Rest attributes to the host's chains, so the host's own operations see them too.
path	String	Host-chosen mount prefix for the mixin's endpoints.
paths	String[]	Host-chosen multiple mount prefixes.
noInherit	String[]	Inheritance-cutoff list for this mixin's sub-context (same tokens as @Rest(noInherit)). Authoritative over the override slots.

Override slots mirroring @Rest attributes of the same name:

Shape	Attributes	Semantics
List-shaped	guards, converters, encoders, serializers, parsers, responseProcessors, restOpArgs, defaultRequestHeaders, defaultResponseHeaders, defaultRequestAttributes, produces, consumes	Appended after the host chain the mixin inherits.
Replace-shaped	partSerializer, partParser, defaultAccept, defaultContentType, defaultCharset, maxInput, roleGuard, rolesDeclared, messages	The host override wins when set.

Host-only attributes (path, paths, children) are never folded into the host by mergeIntoHost. See Mixin Sub-Contexts for the full inheritance semantics and Mixins and Multi-Mount Paths for composition examples.

Related annotations

The following annotations are documented elsewhere but are often used alongside the ones above:

• @Mutating - declares that an operation changes state; see Overloading HTTP Methods.
• Lifecycle annotations (@RestInit, @RestPreCall, ...); see Lifecycle Hooks.
• Parameter annotations (@Path, @Query, @Header, @Content, @Attr, @Method, ...); see Java Method Parameters.