REST Plugin

The official page describes the plugin as high-level support for RESTful, resource-based web applications that is meant to be used with the Convention plugin, and lists its features: Ruby on Rails style REST URLs, zero XML configuration when used with Convention, built-in serialization and deserialization for XML and JSON, automatic error handling, type-safe configuration of the HTTP response and automatic conditional GET support. The plugin jar of 7.4.0 contains a small set of classes that account for all of it:

Source: Struts Plugins — REST, Overview

Source: Struts Plugins — REST, Features

The package it declares, rest-default, extends struts-default, redefines the redirect and redirectAction result types so that they answer 303 See Other, and defines restDefaultStack, which becomes the default interceptor stack of that package. Controllers that live in rest-default get that stack; controllers in any other package do not, which is the reason a controller must not "willfully break its membership" of the package, as the official page puts it.

The Maven coordinates of every Struts plugin come from the struts2-bom, so no version is repeated. The official page asks for two plugins; the verified scenario needs a third dependency, because the plugin registers its XML handler unconditionally and declares the XML library as an optional dependency of its own.

Source: Struts Plugins — REST, Setting Up

Source: Struts 7.4.0 — apps/rest-showcase (its pom lists jackson-dataformat-xml)

With only the first three dependencies the application did not start on Tomcat 11.0.26: the log said that the bean of type ContentTypeHandler with the class JacksonXmlHandler could not be loaded, with the root cause ClassNotFoundException: com.fasterxml.jackson.dataformat.xml.JacksonXmlModule, and every URL answered 404. The plugin brings jackson-core and jackson-databind (2.22.2 for 7.4.0) and XStream 1.4.21 transitively; jackson-dataformat-xml, Apache Juneau and commons-beanutils are optional dependencies of the plugin pom, and the shipped struts-plugin.xml needs the first of them. The version of jackson-dataformat-xml should match the Jackson version of the plugin. The servlet and Pages APIs stay provided, as in the other pages of this section.

Installing the jar already changes the configuration, because the plugin’s struts-plugin.xml sets several constants. The ones that matter at once are struts.mapper.class=rest (every URL is now interpreted as a REST URL), struts.action.extension=xhtml,,xml,json (the extension action is gone) and struts.rest.defaultExtension=xhtml.

RestActionMapper implements the logic of the Rails REST convention. It drops the extension, splits the URI into a namespace and an action name (the longest matching package namespace wins), and, unless a method is already named, guesses the method from the HTTP method and from whether the last path segment is an id. The id is removed from the action name and passed to the action as the request parameter named by struts.mapper.idParameterName (default id).

The method names are constants of the plugin (struts.mapper.indexMethodName, getMethodName (default show), postMethodName, putMethodName, deleteMethodName (default destroy), editMethodName, newMethodName, optionsMethodName, postContinueMethodName and putContinueMethodName), so a team that prefers list and get can rename them. HTML forms cannot send PUT or DELETE; the mapper therefore accepts the request parameter _method: a POST with _method=PUT is a PUT, and any request with _method=DELETE is a DELETE, whatever its HTTP method: GET /books/2.json?_method=DELETE deleted book 2 and answered 204, which makes a state-changing GET that a link prefetcher or a CSRF image tag can trigger (the parameter is read with getParameter, so a query string suffices). The mapper also handles /books/2/edit through the "fun trickery" of its own comment: when the URI ends in action/id/method, the last segment becomes the method name and the previous one the id.

Source: Struts Plugins — REST, RESTful URL Mapping Logic

Source: Struts Javadoc — RestActionMapper

Two details are worth knowing. A name!method URL is parsed, but dynamic method invocation is off by default, so /books!show.json ignored the !show and ran index; the REST convention replaces ! rather than extending it. And a URL with an extension that no handler knows (/books/1.yaml) is not mapped at all: the extension must be in struts.action.extension for the mapper to strip it, and a handler must exist for it to be served.

A controller is an ordinary action whose methods are named after the table above. The Bookshelf controller implements the five core operations and the two form views, extends RestActionSupport to inherit index() and options() (the class below redefines index()), and implements ModelDriven so that only the book, not the whole controller, is serialized. Book is a bean with id, title and author; BookStore is a static in-memory map with two seeded books.

Source: Struts Plugins — REST, Write Your Controller Actions

Source: Struts 7.4.0 — apps/rest-showcase (OrdersController)

The official example returns HttpHeaders from show() and a String from update(), and the controller above does the same; the method edit() of the scenario is analogous to editNew() and omitted. Several points deserve a comment:

The two results of destroy and update are redirects used only by the HTML representation; the JSON and XML representations ignore them, as the next sections show.

The representation of a response is chosen in this order: the extension of the URL (.json, .xml, .xhtml), otherwise the first media type of the Accept header that has a handler, otherwise struts.rest.defaultExtension (xhtml, which means HTML rendered through the Convention results). The representation of a request body is chosen by its Content-Type, and by the extension when the content type is unknown. The five handlers registered by the plugin are:

Source: Struts Plugins — REST, Content Types

Source: Struts Javadoc — ContentTypeHandlerManager

Behaviour that the official page does not state and that was observed: the Accept header is split on commas and the first media type with a handler wins, quality values are ignored (Accept: application/json;q=0.1, text/html;q=0.9 returned JSON); an extension in the URL always beats Accept; and the XML response carries charset=ISO-8859-1 in its Content-Type although the manager writes UTF-8 bytes (the HTML and JSON answers declare UTF-8 and ISO-8859-1 respectively as in the transcripts), which a strict XML client may notice. The official page also says the content types "are supported as incoming data types as well"; a POST of Content-Type: application/xml to a .json URL created a book from <Book><title>XML Book</title><author>Me</author></Book>, and a POST of JSON to a .xml URL created one too and answered an empty body (see restrictToGET below), so the request and response representations are independent.

A controller method may return a String result code, a Result, or an HttpHeaders. The interface has four methods (apply, getStatus, setStatus, getResultCode); DefaultHttpHeaders is the fluent implementation every example uses.

Source: Struts Javadoc — DefaultHttpHeaders.withETag

Source: Struts Javadoc — DefaultHttpHeaders.setLocationId

The full CRUD session of the Bookshelf, abridged: the Date, Vary, cross-origin and ETag headers of some answers are left out.

Source: Struts Plugins — REST, Write Your Controller Actions

Three observations. The null body of the POST and PUT answers is the JSON handler serializing nothing: by default (struts.rest.content.restrictToGET=true) the plugin returns content only for GET, and for a successful POST, PUT or DELETE the client gets the status and headers alone (with false the same POST returned {"id":3,"title":"Hyperion","author":"Dan Simmons"} with status 201). The Location header reuses the extension of the request (books/3.json); a client that asked for JSON follows it to JSON. And the 404 body above is the model, not an error document: a show() that finds nothing should say so explicitly, for instance by returning a different model.

RestActionSupport.options() sets an Allow header built from the methods that the controller class declares (it checks for index, show, edit, editNew, create, update and destroy) and answers 200. The mapper chooses options for any OPTIONS request, but the name is not in the global-allowed-methods of rest-default, so without a declaration the request ends in a 404:

Source: Struts Javadoc — RestActionSupport.options()

The Allow value is the same for /books and /books/1, because it is computed from the class, not from the URL, and it lists a verb for every method the class declares even if that verb makes no sense for the URL. createContinue() and updateContinue() of RestActionSupport answer 100 Continue; the mapper selects them for a POST or PUT that sends Expect: 100-continue. They are not in the global-allowed-methods either: a POST with that header answered the interim 100 and then 404 Method createContinue for action books is not allowed! until createContinue was allowed, so an API whose clients send the header needs @AllowedMethods({"options", "createContinue", "updateContinue"}).

ContentTypeInterceptor runs after params in restDefaultStack. When the request has a body, it opens a reader (with the character encoding of the request, or the JVM default charset when it declares none), selects the handler, and asks it to populate the action, or, for a ModelDriven action, the model. That interceptor is the entry point of the Struts 7 parameter security for REST: with struts.parameters.requireAnnotations=true (the 7.4.0 default) a handler that implements AuthorizationAwareContentTypeHandler (JacksonJsonHandler and JacksonXmlHandler do) reads the body inside an authorization context and every property is checked against @StrutsParameter, with the same rules as for form parameters; any other handler gets a two-phase treatment where the body is read into a fresh instance of the target class and only the authorized properties are copied. The official page documents three consequences:

In the Bookshelf, a POST body that names an id is harmless because create() assigns the id itself: the body {"title":"Y","author":"Z","id":99} created book 4, not 99. A property that the model does not have is not harmless but loud: Jackson’s default of failing on unknown properties turned {"title":"A","author":"B","isbn":"1"} into HTTP 500 (UnrecognizedPropertyException ... Book["isbn"]), and a truncated body ({"title":) into HTTP 500 (JsonEOFException), not a 400.

struts.rest.anySetter.requireAnnotations (7.4.0, default false) decides whether keys bound through a Jackson any-setter need @StrutsParameter(allowDynamicKeys = true); set it to true for any controller with a @JsonAnySetter method.

Source: Struts Plugins — REST, Custom ContentTypeHandlers

Source: Struts Plugins — REST, ModelDriven and @StrutsParameter

Source: Struts — StrutsParameter Annotation

The stack’s validation interceptor calls validate() and the validators of the action; restWorkflow then checks hasErrors(). If there are errors it does not return the input result: it renders the field and action errors through the handler of the request, with the status of struts.rest.validationFailureStatusCode (default 400) and no-cache headers. When the failed method was create it renders the result code editNew, and for update the result code edit, which is what an HTML form needs (the form is redisplayed); for JSON and XML the code is not used.

Source: Struts Javadoc — RestWorkflowInterceptor

The validation and workflow interceptors of restDefaultStack exclude the methods input,back,cancel,browse,index,show,edit,editNew: they are the read operations and the form views. A consequence the official page does not warn about: a conversion error in the id of a read request is not reported. GET /books/abc.json reached show() with id == null (the conversion failed, and the exclusion kept restWorkflow from turning it into a 400) and the controller’s NullPointerException surfaced as an HTML 500. A controller that takes an id should check it, or the package should define its own stack without the exclusion.

The "automatic error handling" of the feature list is narrower than it sounds. An exception thrown by a controller method on a .json URL produced Tomcat’s HTML 500 page, also for Accept: application/json. When the controller mapped the exception to a result with the Convention annotation @ExceptionMapping, the plugin serialized the Throwable itself with status 200: the JSON had cause, message, suppressed and a stackTrace array with class, method and line of every frame (about 34 KB for a three-line failure). That is an information leak and a wrong status; map exceptions to a controller-owned result that returns an HttpHeaders with the right status and a small error model instead, or let a servlet error page handle the error.

The extension xhtml (and the default when nothing is asked) renders a Struts result, so the same controller serves browsers. With the Convention plugin the view of the result code index of the action books is /WEB-INF/content/books-index.jsp, of show is books-show.jsp, of editNew books-editNew.jsp:

Source: Struts Plugins — REST, Write Your Controller Actions (orders-show.jsp)

(The cookie jar only keeps the session id out of the links; without it Tomcat appends ;jsessionid=... to every s:url.) Form handling follows from the mapping table. The form of books-editNew.jsp posts to /books, creating a book; when the title is empty, restWorkflow renders the result editNew again with status 400 and the field error:

Source: Struts Plugins — REST, RESTful URL Mapping Logic (the _method parameter)

An HTML POST that creates answers 201 with a Location header and the body of the result (here a one-word view), not a redirect, because setLocationId forces 201; a browser will show the body. For PUT and DELETE from a form, the parameter _method is used, and the redirect results declared on the controller apply to the HTML representation only:

Source: Struts Plugins — REST, RESTful URL Mapping Logic

The redirect is a 303 See Other (from the redefined redirectAction of rest-default) to a URL that carries the default extension. Without the @Result annotations the same requests executed the operation and then answered 404, No result defined for action ...BooksController and result destroy: the book was deleted and the message said it had not been found, because the plugin does not synthesize views for HTML. The PUT with a JSON content type on a .json URL, in contrast, did not redirect: the JSON handler is used for the response and the redirect result is only used for xhtml.

A handler implements ContentTypeHandler (toObject, fromObject, getContentType, getExtension) and is declared as a bean with the name that identifies it. The Bookshelf offers a read-only CSV representation of the list and of a book:

Source: Struts Plugins — REST, Custom ContentTypeHandlers

Source: Struts Javadoc — ContentTypeHandler

Two steps are easy to forget: the extension must be added to struts.action.extension (otherwise the mapper does not strip it and books.csv is looked up as an action name), and the Accept: text/csv request works because the handler declares that content type. To replace a built-in handler for an extension instead of adding one, declare a second bean for the same extension and name it in struts.rest.handlerOverride.EXTENSION; with a csvSemi bean (a subclass whose separator is ;), <constant name="struts.rest.handlerOverride.csv" value="csvSemi"/> made books.csv answer id;title;author. A handler that reads bodies and should honour @StrutsParameter implements AuthorizationAwareContentTypeHandler, a marker sub-interface. The official page also describes customising XStream (XStreamProvider, XStreamAllowedClasses, XStreamAllowedClassNames, XStreamPermissionProvider, since 6.1.0); those interfaces are implemented by an action and apply to XStreamHandler, which is not one of the handlers registered by the plugin in 7.4.0: to use it, register it yourself as a ContentTypeHandler bean.

The constants of the plugin, with the defaults of struts-plugin.xml and RestConstants at 7.4.0:

Source: Struts Plugins — REST, Settings

Source: Struts 7.4.0 — plugins/rest (struts-plugin.xml, RestConstants)

The official table omits the method-name constants for options and the two Continue methods and lists the namespace constant without its effect; the table above follows the sources.

Two changes of 7.4.0 and 6.12.0 matter for any REST API. The first closes a denial-of-service hole: before, the request body was read into memory with no bound. ContentTypeInterceptor now stops reading once the body exceeds struts.rest.content.maxLength characters (2 MB by default) and fails the request with RequestBodyTooLargeException before the action runs. The limit applies where the handler reads the body, so form-urlencoded and multipart requests are unaffected. With the constant set to 100 for the test:

Source: Struts Plugins — REST, Request body size limit

Source: Struts Security Bulletin — S2-077 (CVE-2026-104713)

The answer is a 500, not a 413, so a gateway in front of the application should enforce its own size limits too. An API that accepts JSON or XML payloads above 2 MB must raise the constant when upgrading, or those requests start failing. The bulletin S2-077 rates the issue Important and affects 2.1.8 to 2.3.37, 2.5.0 to 2.5.33, 6.0.0 to 6.11.0 and 7.0.0 to 7.3.0. The fixed releases are 7.4.0 and 6.12.0.

The second change: restDefaultStack now contains the coep, coop and fetchMetadata interceptors, configured as in the core defaultStack (WW-5718). Before, a package extending rest-default sent no COOP and COEP headers and skipped the Fetch Metadata check. The check rejects browser requests with Sec-Fetch-Site: cross-site that use a method other than GET and are not navigations; the rejection is HTTP 403 without a body:

A single-page application served from another site that calls the API with fetch() needs the check disabled for the stack that serves it, which is a deliberate decision (CORS is configured elsewhere):

Source: Struts Plugins — REST, Resource isolation in restDefaultStack

Source: Struts — Fetch Metadata Interceptor

Requests from non-browser clients carry no Sec-Fetch-Site header and are not affected, which is why the curl examples above work unmodified.

Before the plugin, the core had two mappers that predate it: RestfulActionMapper (URLs of the form /action/param/value/param/value) and Restful2ActionMapper (an earlier design with method guessing and the parameter __http_method to simulate PUT and DELETE). Both are deprecated since 7.4.0 and 6.12.0 and are to be removed (WW-5707); the official page of the core guide says to use the REST plugin instead. The reason to know them is the security bulletin S2-075 (see Security Bulletins; CVE-2026-104711): if an application is configured to use the legacy RestfulActionMapper, a crafted request can inject an OGNL expression that may lead to remote code execution; Struts 7 is affected up to 7.3.0 only when the OGNL allowlist is disabled, which it is not by default, and applications using the default mapper, the restful2 mapper or the REST plugin are not affected. The fix is in 7.4.0 and 6.12.0; the workaround is to stop using RestfulActionMapper.

An application that still has the restful2 mapper can keep it per namespace with the same prefix technique as above. The verified configuration (a classic action with wildcard and the id taken from the name):

Source: Struts Core Developer Guide — RestfulActionMapper, Restful2ActionMapper

Source: Struts Core Developer Guide — Restful2ActionMapper, Example

Source: Struts Security Bulletin — S2-075 (CVE-2026-104711)

A migration from Restful2ActionMapper to the plugin renames view to show and remove to destroy, replaces __http_method by _method, and moves from wildcard actions with {1} parameters to controllers whose id is injected by the mapper (@StrutsParameter on the setter).

The Struts repository ships apps/rest-showcase, the application behind the official page: a Maven project that depends on the REST, Convention and config browser plugins plus jackson-dataformat-xml, with the package org.demo.rest.example holding OrdersController, Order, OrdersService and IndexController, and five JSPs under WEB-INF/content (orders-index.jsp, orders-show.jsp, orders-edit.jsp, orders-editNew.jsp, orders-deleteConfirm.jsp). Its struts.xml is the REST-only configuration of this page (suffix Controller, mapAllMatches, a locator) with a package rest-showcase that extends rest-default and lists deleteConfirm among the allowed methods. The controller follows the same pattern as the Bookshelf one: ModelDriven<Object> returning a list for index and the order otherwise, an @StrutsParameter on setId, HttpHeaders from show, index and create, and @Result(name="success", type="redirectAction") for the HTML flow. It also shows a custom method name reached through the URL trick of the mapper: GET /orders/1/deleteConfirm calls deleteConfirm() because the last segment of action/id/method becomes the method. It is the quickest way to see the Convention naming of the views and the restDefaultStack in a running application; the struts-examples repository keeps the larger collection of Struts sample projects.

Source: Struts 7.4.0 — apps/rest-showcase

Source: Apache Struts Examples

The older Struts 2 books were written before the REST plugin matured and before the Jakarta, Java 17 and Struts 7 changes. Following the concept table of this documentation, the Ajax chapters of the era teach hand-built XStream JSON results and the Dojo plugin, which are replaced by the JSON plugin, the REST plugin and plain fetch calls; examples import com.opensymphony.xwork2.* (now org.apache.struts2.*), call actions as action!method (dynamic method invocation is off by default and the REST mapper ignores it) and map *.action URLs, which the plugin removes from the extension list. The official page and the plugin of 7.4.0 disagree with the behaviour verified on Tomcat 11:

The REST plugin fits a Struts application that needs a handful of resource endpoints beside its pages, or a team that already owns Struts controllers and wants JSON and XML for the same logic with the Rails-style URLs. For a JSON endpoint attached to a classic action (a json result, root, includeProperties), the JSON plugin of this section is simpler; it has its own struts.json.maxLength limit. A new API-first service is better built with Spring MVC or another API framework, because the plugin has no content negotiation beyond the extension, no error document, no OpenAPI integration and no automatic CORS; see REST APIs with Spring MVC and WebFlux for that style. The security pages of this section (Security Hardening and Security Headers and Fetch Metadata) cover the surrounding hardening: size limits at the gateway, CORS, authentication, and the OGNL allowlist. The classic actions and interceptors that the controllers build on are in Actions and Interceptors, the action configuration in Configuration: struts.xml and Constants and the mapper in Packages and Namespaces; model-driven controllers are covered in Model Driven, Preparable and CRUD, and the form side of the validation errors in Validation.