Struts API
The Struts API is a control layerLayerLogical separation of functionality within a single system/application, focused on code organization. for NS JEE applicationsApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. built on Apache Struts 2. It exposes a JSON API for all data elementsData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. in the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution., covering CRUD operations, findersFinderA search specification combining field-operator pairs to execute standard data queries on a DataElement., projectionsProjectionA tailored subset of fields on a DataElement designed to encapsulate data for a specific technical or functional view., tasks and data commandsData Command (DataCommand). [Deprecated] A legacy mechanism used for data input and custom action execution on DataElements, replaced by DataOperations.. The Struts API is meant to serve the Knockout frontend.
The Struts API is included in the minimal-jee-beam. For modular setups, such as one based on the jee-backend-beam,
it is available separately as the struts-api-beam.
The Struts API is still maintained, but it no longer receives new features. For new projects, use the Standard API.
Endpoints
Every data elementData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. gets a set of JSON endpoints. The endpoints are grouped per component and follow the URL pattern:
/<application>/<component>/<dataElement>-<action>-json
For example, the details of the data elementData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. Person in the component crm are available at
/<application>/crm/person-detail-json. Parameters are passed as request parameters or in a JSON request body. The
instance identifier is passed as <dataElement>Oid, for example personOid.
| Action | Description | Main parameters |
|---|---|---|
detail | Returns the details projectionProjectionA tailored subset of fields on a DataElement designed to encapsulate data for a specific technical or functional view. of one instance. | <dataElement>Oid |
search | Executes a finder and returns a page of results. | searchMethod, details.<field>, page, rowsPerPage, sortFields, fetchAll, projection |
saveDetails, confirm | Creates a new instance, or updates an existing instance when <dataElement>Oid is given. | <dataElement>Oid, <dataElement>.<field> |
delete | Deletes one instance. | <dataElement>Oid |
modify | Updates an instance with a projectionProjectionA tailored subset of fields on a DataElement designed to encapsulate data for a specific technical or functional view.. Only available with the option cruds.modifyWithProjection. | projection, details.<field> |
perform | Performs a task on an instance, or sets the status of a task. | <dataElement>Oid, taskName, paramString, targetStatus |
getProjection | Returns one instance in the requested projection. | id, projection |
perform-command | Performs a data command and returns a commandResult. | commandName, command.<field> |
upload | Imports a file. Only available for data elementsData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. with the tag #io.import. | type, file |
download | Exports a file. Only available for data elementsData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. with the tag #io.export. | type |
In addition to the data elementData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept. endpoints, the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. exposes some general endpoints in the root namespace:
| Action | Description |
|---|---|
translate-json | Translates text. |
menu-json | Returns the menu for an applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. and role. |
findersForDataElement-json | Returns all findersFinderA search specification combining field-operator pairs to execute standard data queries on a DataElement. for a data elementData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept.. |
getComponentMetaData-json | Returns the metadata of a component. |
getDataElementMetaData-json | Returns the metadata of a data elementData Element (DataElement). A fundamental data concept or entity within an application's domain, acting as an anthropomorphic translation of a real-life object or concept.. |
getApplicationProperties-json | Returns the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. properties. |
request-nonce-json | Returns a nonce for CSRF protection. |
Security
When the applicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. contains the account base component,
the Struts API uses it for authentication and authorization. Interceptors on all endpoints check the user session and
the access rights of the user.
The implementations for authentication and authorization can be changed through the account.ns.properties file. See
Customizing authorization.
ApplicationApplicationInstanceAdds protection against cross-site request forgery to all
endpoints that change data. The client requests a nonce from request-nonce-json and sends it in the request
parameter. Each nonce can only be used once and stays valid for 30 minutes.
<options>
<struts.security.csrfProtection/>
</options>
ApplicationApplicationInstanceEnforces the correct HTTP method on each request. Endpoints that retrieve data only accept GET. Endpoints that change
data only accept POST. Other methods return the status 405 Method Not Allowed.
<options>
<struts.security.enforceHttpMethod/>
</options>
ApplicationApplicationInstanceEnforces the use of the @StrutsParameter annotation in Struts actions. Struts then only injects request parameters into
setters with this annotation, or in objects returned by getters with this annotation. Add the annotation to custom
actions as well.
<options>
<experimental.struts.security.enforceAnnotatedParameters/>
</options>
ApplicationApplicationInstanceSets what happens when an unauthorized user calls an endpoint. With redirect, the default, the user is redirected to
the login page. With error-page, a dedicated error page is shown.
<options>
<struts.unauthorized>redirect</struts.unauthorized>
</options>
<options>
<struts.unauthorized>error-page</struts.unauthorized>
</options>
Authentication methods
The account component supports two authentication methods for the Struts API:
- Username and password: The default login form. Disable it with the option
baseComponents.authentication.disableInternalAuth. - OpenID Connect: Enable it with the option
baseComponents.authentication.enableOIDCand configure the providers in theaccount.ns.propertiesfile. See OpenID Connect.
Configuration and customization
JSON payload limits
The NSXJsonInterceptor reads the JSON request body. By default, it does not limit the size of the payload. You can
set limits with the following Struts constants:
| Constant | Limits |
|---|---|
nsx.struts.json.maxElements | The number of elements. |
nsx.struts.json.maxDepth | The nesting depth. |
nsx.struts.json.maxLength | The total length of the payload. |
nsx.struts.json.maxStringLength | The length of a string value. |
nsx.struts.json.maxKeyLength | The length of a key. |
Add the constants to the custom-constants anchorAnchorA marker within generated source code reserved for adding custom logic during re-expansion. of struts-header.xml:
<!-- anchor:custom-constants:start -->
<constant name="nsx.struts.json.maxDepth" value="20"/>
<constant name="nsx.struts.json.maxStringLength" value="100000"/>
<!-- anchor:custom-constants:end -->
The JSON payload limits are available as of minimal-jee-beam 2.5.0 and struts-api-beam 1.3.0.
Custom JSON serialization
The Struts API serializes responses with the NSXJSONWriter class, which is configured as struts.json.writer. To
customize the serialization of objects, add custom code in the struts-json-writer-process custom anchorAnchorA marker within generated source code reserved for adding custom logic during re-expansion. of
NSXJSONWriter.java.
Before minimal-jee-beam 2.5.0 and struts-api-beam 1.3.0, a custom struts.json.writer could be configured. Move
such customizations to the NSXJSONWriter class.