Correct Implementation of JSON POST Request Body in OkHttp

Analysis of Common Issues with JSON POST Requests

When migrating from the Ion library to OkHttp in Android development, developers frequently encounter 400 errors with JSON POST requests. This typically stems from misunderstandings about request body formatting. The manual JSON string concatenation approach in the original code has significant flaws:

String reason = menuItem.getTitle().toString();
// Incorrect example: manual JSON string concatenation
String jsonString = "{\"Reason\": \"" + reason + "\"}";
RequestBody body = RequestBody.create(
    MediaType.parse("application/json"),
    jsonString
);

This method is prone to JSON formatting errors, especially when strings contain special characters. For instance, if reason contains quotation marks or line breaks, the generated JSON will be invalid.

Proper JSON Request Body Construction

The best practice is to use Android's built-in JSONObject class or third-party JSON libraries (like Gson) to construct JSON data, then call the toString() method to generate standardized JSON strings. This approach ensures the generated JSON complies with specifications and avoids syntax errors.

// Correct example: using JSONObject to build JSON
JSONObject json = new JSONObject();
try {
    json.put("Reason", reason);
} catch (JSONException e) {
    e.printStackTrace();
}

// Define MediaType with character encoding
public static final MediaType JSON = 
    MediaType.parse("application/json; charset=utf-8");

// Create RequestBody
RequestBody body = RequestBody.create(json.toString(), JSON);

Note that the MediaType definition should include charset=utf-8, ensuring proper parsing of non-ASCII characters like Chinese text.

Complete OkHttp POST Request Implementation

Below is a complete asynchronous POST request example combining JSON construction and error handling:

OkHttpClient client = new OkHttpClient();

String url = mBaseUrl + "/" + id + "/report";

// Build JSON request body
JSONObject jsonBody = new JSONObject();
try {
    jsonBody.put("Reason", menuItem.getTitle().toString());
} catch (JSONException e) {
    Log.e("JSONError", "Failed to create JSON", e);
    return;
}

RequestBody requestBody = RequestBody.create(
    jsonBody.toString(), 
    MediaType.parse("application/json; charset=utf-8")
);

// Build request
Request request = new Request.Builder()
    .url(url)
    .header("X-Client-Type", "Android")
    .post(requestBody)
    .build();

// Execute asynchronous request
client.newCall(request).enqueue(new Callback() {
    @Override
    public void onFailure(Call call, IOException e) {
        // Network error handling
        Log.e("NetworkError", "Request failed", e);
        runOnUiThread(() -> 
            Toast.makeText(context, "Network error", Toast.LENGTH_SHORT).show()
        );
    }

    @Override
    public void onResponse(Call call, Response response) throws IOException {
        if (!response.isSuccessful()) {
            // HTTP error handling (e.g., 400, 500)
            Log.e("HTTPError", "Unexpected code " + response.code());
            throw new IOException("Unexpected code " + response);
        }
        
        // Success response handling
        runOnUiThread(() -> 
            Toast.makeText(context, "Report Received", Toast.LENGTH_SHORT).show()
        );
        
        // Optional: read response body
        String responseBody = response.body().string();
        Log.d("Response", responseBody);
    }
});

Comparison with Ion Library and Migration Recommendations

Ion's .setJsonObjectBody(json) method internally handles JSON serialization and MediaType configuration automatically, while OkHttp requires explicit configuration of these details. During migration, pay attention to:

1. Replace manual JSON string concatenation with JSONObject.toString()
2. Correctly set MediaType to "application/json; charset=utf-8"
3. When using RequestBody.create(), the parameter order is (content, mediaType)
4. OkHttp's asynchronous callbacks execute on background threads; use runOnUiThread for UI updates

Advanced Configuration and Best Practices

For more complex application scenarios, consider:

• Using Gson or Moshi libraries for automatic object-JSON serialization/deserialization
• Configuring OkHttpClient with connection timeouts, read timeouts, and interceptors
• Compressing JSON request bodies to reduce network transmission
• Implementing retry mechanisms for temporary network failures

By following these practices, you can ensure the reliability and performance of JSON POST requests while avoiding common 400 errors.