JSON-Only Communication - I built a lightweight Java framework for Japan's "SI" projects (third attempt in 10 years) #003

#java #framework #json #ajax

Introduction

This time, I'll cover "JSON-only communication," a core design principle of SIcore.

What This Article Covers

What "JSON-only communication" means
Browser ⇔ Server data flow
Role separation and page transition approach (differences from JSP-style approach)
Benefits / Drawbacks

What is "JSON-Only Communication"?

In SIcore, communication between browser and server is limited to JSON.

Requests to web services are sent in JSON format (or URL parameters)
Responses from web services are returned in JSON format only
HTML files are retrieved by the browser as static files (server does not generate HTML dynamically)

In other words, the design principle is: "The server never returns HTML with data embedded."

Browser ⇔ Server Data Flow

[Browser] Display web page
     │
     │ 1. Input → Button click
     ▼
[JavaScript]
     │ 2. Generate JSON from HTML input values and call web service
     ▼
[Web Service (Java)]
     │ 3. Receive JSON, process it, and return JSON
     ▼
[JavaScript]
     │ 4. Set JSON (web service response) to HTML
     ▼
[Browser] Display updated

Web Page (Browser) Side: Role Separation of HTML and JavaScript

HTML: Container for user input and display
JavaScript: Create request JSON from input values, call web service, display response JSON on screen

// Create request JSON from input values
const req = PageUtil.getValues();
// Call web service
const res = await HttpUtil.callJsonService('/services/exmodule/ExampleListSearch', req);
// Display response JSON
PageUtil.setValues(res);

Web Service (Server) Side: Processing with Map Class

A slight digression:
In SIcore, the server side handles JSON data as a Map.
This Map serves as both the container for request data and the container for response data.

  /** Web service processing **/
  public void doExecute(Map io) {
    // Get HTML input value from request
    String userId = (String) io.get("user_id");
    //  :
    // Do some processing
    //  :
    // Return as response
    io.put("user_nm", "...");
  }

With this "request and response as one" design, developers write less code and can implement the server side with the same feel as handling web page values (similar to JavaScript).

Page Transitions: "Fetch HTML" + "Fetch Initial Values"

This is where the approach differs most from traditional JSP thinking.

JSP-Style Approach (Server creates the next page's HTML)

Form submission (submit)
Web service processing
- On success, server creates and returns the destination HTML (JSP) with initial values embedded

JSON-Only Design (HTML is static, server doesn't create HTML)

JSON submission
Web service processing (returns JSON results)
On success, browser fetches the destination HTML (static file)
Initial JavaScript processing on the destination page fetches initial values from the web service and displays them

WebAPI (Server-to-Server Communication) Uses the Same Approach

When the "server ⇔ server" interface is also aligned to JSON-only, you can implement it with the same coding style as "browser ⇔ server" processing.
Additionally, since the boundary between UI and API becomes clear, you can easily reuse "browser ⇔ server" processing code for "server ⇔ server" processing.

Easy to Test with Postman and Similar Tools

You can:

Send request JSON with Postman
Check the response JSON returned

This approach allows you to test the server side even before the web pages are complete.

Benefits

Many of these are benefits of Ajax in general:

Full page redraws become unnecessary—you can update only the parts you need. This makes state preservation (search conditions, etc.) on the browser side easier
Clear separation of responsibilities between web page and web server (HTML is static, business logic is in Java)
Combined with URL mapping, reduces "places to get confused (configuration, magic)" (helpful for beginners and AI)
Easy to implement processes that require user confirmation in the middle of web server processing
There are cases where you use browser-side storage (sessionStorage) after successful completion (not available in JSP)
Simply reduces communication volume

Drawbacks

JavaScript processing is always required for data transmission/reception, which increases the risk of browser-side errors (risk common to Ajax)
The "page transition on success and display" approach can be confusing if you code it with the same mindset as JSP
- Destination HTML is fetched statically
- Initial display values are fetched via JSON
- It becomes a two-step process
File uploads cannot be completed with JSON alone, requiring a separate approach (multipart form submission, etc.)

Conclusion

JSON-only design is not an "all-purpose design that can do anything."
It's a trade-off to build web business applications in a consistent pattern, quickly and without confusion.

In the next article, I plan to dive deeper into handling "static HTML" that was mentioned in this article.

Check out the other articles in this series!