standard-api-expanders
The jaxrs-standard-api-expanders
is a new expander bundle which implements a fully generated API based directly on the
elements model for a JEE application. It is intended to be an alternative to Struts2 to support a fully generated UI.
The documentation for the JAX-RS standard API is under construction. Not all topics are currently covered.
Overview
By adding the cascading option experimental.control.cruds.jaxrs
at any level of the application down to DataElement,
it is possible to enable the new JAX-RS based API. This will also trigger the use of this API as the backend for the
Knockout-based generated UI. As the jaxrs-standard-api-expanders
resource is included in the nsx-default-stack
,
it should always be available when generating a JEE application.
This API implements the JSON:API 1.1 standard wherever possible. If there are any part sof the API that did not match this standard, such as the use of file IO or DataCommands, these endpoints were implemented under a different MediaType to indicate that they fall outside of this standard. There will therefor also not be any references from the implementation that uses JSON:API to parts that do not, only in the other direction.
Expansion resources
Whereas the current default Struts2-based API we use for our generated Knockout UI is currently still part fo the
Expanders
resource which generates the JEE application stack, the new JAX-RS based standard API has been built as a
modular addon for the JEE application stack.
Resource landscape
As shown in the diagram, the standard API is provided primarily by the jaxrs-standard-api-expanders
resource, which
depends on Expanders
. Individual functionalities and concerns are split off into separate resources which are all
directly or transitively part of the nsx-default-stack
expansion resource.
Main resources
All listed resources are currently available under groupId
net.democritus.api.rest
and follow versioning ofstandard-api-expanders
, currently on version0.3.0
.
jaxrs-standard-api-expanders
: Provides the main API infrastructure such as error handling and endpoints for all standard CRUDs operations and finders, compliant with the JSON:API standard. The resource also expands API documentation in the form of a modular YAML-based OpenAPI v3 specification.jaxrs-standard-api-fileio-expanders
: Provides additional functionality to expose file upload and download endpoints represented by Fields in DataElements. As this is not covered by JSON:API, these endpoints do not consume theapplication/vnd.api+json
media type forJSON:API
. All errors message are still in the JSON:API format.jaxrs-standard-api-datacommands-expanders
: Provides additional functionality to expose endpoints for DataCommands. As operations are not covered by JSON:API, these endpoints do not consume theapplication/vnd.api+json
media type forJSON:API
, but ratherapplication/json
. All errors message are still in the JSON:API format.
Base-components resources
All listed resources are currently available under groupId
net.democritus
and follow versioning ofbase-components
, currently on version2024.5.3
.
account-component-standard-api-expanders
: This resource as part ofbase-components
provides authentication and authorization implementations for the relevant interceptors in the API pipeline, that integrate with theaccount
Component.assets-component-standard-api-expanders
: This resource as part ofbase-components
provides the implementation for file upload and download endpoints of thejaxrs-standard-api-fileio-expanders
resource when they are represented as links to theassets::Asset
element. For backwards compatibility with the current Knockout-based UI, this resource also provides two endpoints to upload files to and download files from the Asset DataElement directly, rather than the new default approach of treating Asset as a file storage provider without direct user-interaction.
Web-styles resources
All listed resources are currently available under groupId
net.democritus
and follow versioning ofweb-styles
, currently on version2024.6.1
.
knockout-jaxrs-stdapi-expanders
: This resource as part ofweb-styles
provides an agent implementation for our Knockout-based UI, that makes it possible to use the existing UI with the new API, rather than the Struts2-based API.web-servlet-expanders
: This resource generates new servlets for the JEE application that can serve static web resources such as stylesheets without these being served by a specific API provider such as Struts2.
QuerySearch resources
All listed resources are currently available under groupId
net.democritus
and follow versioning ofquerysearch-expanders
, currently on version3.3.1
.
querysearch-standard-api-expanders
: This resource provides endpoints and routing for filter operations based on QuerySearch, rather than finders. While this implementation also complies with JSON:API, the structure of parameters is slightly different from that of finders, due to finders using FieldOperatorPairs.
API Documentation
The API is documented extensively in an expanded OpenAPI v3 specification, which can be found in the following location:
<expansionRoot>/control/openapi/<application>.yaml
.
Each expansion resource that provides API endpoints is responsible for adding its own OpenAPI-based documentation. The
included README.md
file in the same folder also contains instructions on how to merge the entire specification into a
single YAML or JSON file in case there is a need for this.
At time of writing, the endpoints for uploading/downloading directly to/from assets:Asset
, as well as the endpoints
for QuerySearch are not yet available in the OpenAPI specification.
Known issues
- Not all errors are covered by the error handling system. Some errors may not return a JSON:API-based error payload.
- Support for collection-based link fields is not yet finished and planned for the next update.
- Timestamp formatting is not yet implemented for payloads, this will also be covered in the next update. We aim to
consistently make use of the same RFC3339 format used by
rest-expanders
, but this will likely be configurable as well by creating new value types. - Support to handle data validation is limited at this time.
- Support for CORS pre-flight requests is not yet implemented, but will be ported from
rest-expanders
, which already has a comprehensive implementation for this.