[
https://issues.apache.org/jira/browse/FINERACT-2021?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Aleksandar Vidakovic resolved FINERACT-2021.
--------------------------------------------
Fix Version/s: 1.15.0
Resolution: Duplicate
> Type-safe REST API layer
> ------------------------
>
> Key: FINERACT-2021
> URL: https://issues.apache.org/jira/browse/FINERACT-2021
> Project: Apache Fineract
> Issue Type: Improvement
> Reporter: Aleksandar Vidakovic
> Assignee: Aleksandar Vidakovic
> Priority: Major
> Labels: FIPS
> Fix For: 1.15.0
>
>
> h2. Background and Motivation
> Fineract initial planning and code architecture predates some of the
> frameworks and current best practices. That and the fact that we have some
> not so easy to parse data structures led to the decision to use Google's GSON
> library and parse incoming API requests manually and to capture all request
> bodies in String variables. The downside of doing this decision are:
> * by capturing all incoming request bodies in Strings we lose all type
> information
> * we need to manually reintroduce types by creating dummy classes that are
> solely there to create an OpenAPI descriptor
> * it is easy to introduce bugs while refactoring, because non of the
> refactoring tools in any of the IDEs can help
> * we have to maintain a lot of "magic" Strings to poke into the JSON data
> structures (again, no type-safety)
> * we have a lot of boilerplate code for manual JSON parsing that we have to
> maintain (rough estimate 10-15% of the entire code base)
> * because the JSON parsing is so tedious and time consuming a couple of
> developers decided to skip the layered architecture rules; and with that they
> tied the REST API layer to the business logic/service layer (not a good
> practice); the business logic should not contain any information about how
> and in which format we exchange API requests
> h2. Target Personas
> * developers
> * integrators
> * BaaS
> h2. Goals
> * migrate current JAX-RS REST resource classes to Spring's Web MVC
> * use Spring Boot's first class integration of Jackson for JSON parsing
> * get rid of entire manual JSON code base (including the use of GSON)
> * handle difficult/non-standard data structures with Jackson Serializer and
> Deserializer implementations
> * all incoming and outgoing API requests need to be mapped to proper Java
> classes in packages "data"
> * all business logic services need to have "data" classes as input and
> output parameters
> * remove all JSON related input and output parameters from business logic
> services
> * remove all dummy/helper classes related to OpenAPI descriptor generation
> * clear separation between data and domain/entity classes
> * domain classes should be only used internal to respective business logic
> service and not leak outside of its package/feature/module
> * use MapStruct ([https://mapstruct.org/)] to generate as much mapping code
> as possible without manual intervention (mappers should only be used internal
> to business logic services)
> * use validation annotations on data classes to delegate as much as possible
> to Java validation framework instead of doing our own boilerplate
> "if-then-else" code
> * keep REST API backwards compatibility with version 1.9.0
> h2. Non-Goals
> * change/improve REST API structure
> * move all current RESTeasy based integration tests to Spring MVC's JUnit
> test support (separate project/pull request/ticket)
> h2. Proposed API Changes
> h3. JAX-RS REST resource classes
> Move all JAX-RS REST resource classes to Spring Web MVC controllers (with all
> annotations etc.). It might be possible to use OpenRewrite to automate part
> of this work (there is a module for refactoring JAX-RS to Spring Web MVC.
> This allows us to take advantage of first class support for JUnit like
> testing in Spring (replacing our unmaintainable integration tests... which
> lack themselves type safety).
> h3. REST controller input and output parameters
> Make sure all endpoint receive and generate type safe data. All input/output
> parameter related data structures should reside in "data" packages.
> h3. Business logic services
> All input and output parameters in the business logic layer need to be mapped
> to "data" classes. Internal domain/entity classes should not leak outside of
> the business logic classes.
> h3. Data/DTO to domain/entity mapping
> All mapping between data and domain classes should be mapped with MapStruct.
> The developers only have to provide annotations (if necessary) and automate
> the mapping code generation with MapStruct.
> h2. Risks
> Migrating from JAX-RS to Spring Web MVC and re-introduce type-safety will be
> an ongoing effort over a couple of weeks/months. During that time we'll have
> 2 different frameworks handling the API requests. There might be subtle
> changes in the behavior.
> h2. ETA
> We have roughly 50 feature packages/modules with REST API resource classes.
> Some are larger than others; first migrations could take a bit longer before
> we establish a routine. A rough calculation would be 3-4 days per
> feature/module which results in 150-200 development days or about 6 months to
> finish this task.
> h2. Diagrams
> TBD
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
