Skip to main content

standard-api-expanders

net.democritus.api.rest:jaxrs-standard-api-expanders::0.15.1

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.

caution

The documentation for the JAX-RS standard API is under construction. Not all topics are currently covered.

Overview​

Option
experimental.control.cruds.jaxrs ApplicationApplicationInstanceComponentDataElement

Enables the generation of a fully featured JAX-RS based REST API.

<options>
  <experimental.control.cruds.jaxrs/>
</options>

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 of standard-api-expanders, currently on version 0.15.1.

  • 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 the application/vnd.api+json media type for JSON: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 the application/vnd.api+json media type for JSON:API, but rather application/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 of base-components, currently on version 2024.7.2.

  • account-component-standard-api-expanders: This resource as part of base-components provides authentication and authorization implementations for the relevant interceptors in the API pipeline, that integrate with the account Component.
  • assets-component-standard-api-expanders: This resource as part of base-components provides the implementation for file upload and download endpoints of the jaxrs-standard-api-fileio-expanders resource when they are represented as links to the assets::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 of web-styles, currently on version 2024.8.0.

  • knockout-jaxrs-stdapi-expanders: This resource as part of web-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 of querysearch-expanders, currently on version 3.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.

caution

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 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.