JSON APIs

🎁 JSON APIs in Jakarta EE: Your Magic Toolkit for Data!

Imagine you have a magical toy box that can hold any toy in the world. But here’s the catch – you need special tools to put toys in, take them out, find specific ones, and even change them while they’re inside!

That’s exactly what JSON APIs are in Jakarta EE. JSON is like the universal language that all apps speak, and these APIs are your special tools to work with it!

🧩 The Six Magic Tools

Think of these six tools like a superhero’s utility belt:

🏗️ JSON Object Model: Building with LEGO Blocks

The Story

Imagine you’re building a LEGO house. You pick up each brick, connect them together, and when you’re done – you have a complete structure you can look at from any angle!

JSON Object Model works the same way. You build your JSON piece by piece, and once it’s built, you can explore it however you want.

Building JSON (Like stacking LEGO)

JsonObject person = Json.createObjectBuilder()
    .add("name", "Maya")
    .add("age", 10)
    .add("hobbies", Json.createArrayBuilder()
        .add("reading")
        .add("coding"))
    .build();

This creates:

{
  "name": "Maya",
  "age": 10,
  "hobbies": ["reading", "coding"]
}

Reading JSON (Like examining your LEGO creation)

String name = person.getString("name");
int age = person.getInt("age");
JsonArray hobbies = person.getJsonArray("hobbies");

💡 Key Insight

The Object Model loads everything into memory at once. Great for small data, but be careful with huge files!

graph TD
    A["JSON String"] --> B["Parse All At Once"]
    B --> C["JsonObject in Memory"]
    C --> D["Read Any Part Instantly"]

🏭 JSON Streaming API: The Conveyor Belt

The Story

Picture a factory conveyor belt. Items come one by one. You check each item as it passes, decide what to do, then move to the next. You never see the whole pile at once!

Streaming API reads or writes JSON piece by piece – perfect for huge data that won’t fit in memory.

Two Parts to Streaming

1. JsonParser (Reading) – Like watching items on a conveyor belt:

JsonParser parser = Json.createParser(inputStream);

while (parser.hasNext()) {
    Event event = parser.next();

    if (event == Event.KEY_NAME) {
        String key = parser.getString();
    }
    if (event == Event.VALUE_STRING) {
        String value = parser.getString();
    }
}

2. JsonGenerator (Writing) – Like placing items on a conveyor belt:

JsonGenerator gen = Json.createGenerator(outputStream);

gen.writeStartObject()
   .write("name", "Leo")
   .write("score", 100)
   .writeEnd();

gen.close();

🎯 When to Use What?

graph TD
    A["Small JSON"] --> B["Object Model"]
    C["Huge JSON"] --> D["Streaming API"]
    D --> E["Read piece by piece"]
    D --> F["Low memory usage"]

🎯 JSON Pointer: GPS for Your Data

The Story

You’re in a huge library with millions of books. Instead of wandering around, you use a GPS that tells you: “Go to Floor 3, Section B, Shelf 5, Book 12.”

JSON Pointer is that GPS. It takes you directly to any piece of data!

The Syntax

A JSON Pointer is a string starting with /, with each part separated by /:

/users/0/name
   ↓    ↓   ↓
   |    |   └── the "name" field
   |    └────── first item (index 0)
   └─────────── the "users" array

Example in Action

Given this JSON:

{
  "store": {
    "books": [
      {"title": "Adventure Time", "price": 12},
      {"title": "Space Quest", "price": 15}
    ]
  }
}

JsonPointer pointer = Json.createPointer("/store/books/1/title");
JsonString title = (JsonString) pointer.getValue(jsonObject);
// Returns: "Space Quest"

🎨 Special Characters

// To access key "a/b" use:
JsonPointer p = Json.createPointer("/keys/a~1b");

✂️ JSON Patch: Surgical Edits

The Story

Imagine you have a photo and want to change just the eye color, not redraw the whole picture. You use a tiny, precise brush!

JSON Patch lets you describe exactly what changes to make without sending the whole document. Super efficient!

The Operations

There are 6 operations you can do:

Patch in Action

JsonPatch patch = Json.createPatchBuilder()
    .add("/nickname", "Max")
    .replace("/age", 11)
    .remove("/oldField")
    .build();

JsonObject updated = patch.apply(original);

The Patch Format (RFC 6902)

[
  {"op": "add", "path": "/email", "value": "max@example.com"},
  {"op": "replace", "path": "/score", "value": 200},
  {"op": "test", "path": "/active", "value": true}
]

💡 Why test Matters

The test operation ensures a value is what you expect before making changes. If the test fails, the whole patch is rejected!

graph TD
    A["Original JSON"] --> B["Apply Patch"]
    B --> C{Test Passes?}
    C -->|Yes| D["Apply Changes"]
    C -->|No| E["Reject All"]

🌟 JSON-B Annotations: The Magic Translator

The Story

Imagine you have a translator who instantly converts English to French and back. You just speak normally, and they handle everything!

JSON-B (JSON Binding) automatically converts Java objects to JSON and back. Annotations customize how the translation works!

Key Annotations

@JsonbProperty – Rename fields:

public class Hero {
    @JsonbProperty("hero_name")
    private String name;  // becomes "hero_name" in JSON
}

@JsonbTransient – Skip fields:

public class User {
    private String name;

    @JsonbTransient
    private String password;  // Never in JSON!
}

@JsonbDateFormat – Format dates:

public class Event {
    @JsonbDateFormat("yyyy-MM-dd")
    private LocalDate eventDate;
}

@JsonbNumberFormat – Format numbers:

public class Product {
    @JsonbNumberFormat("#,##0.00")
    private double price;  // "1,234.56"
}

Quick Conversion

Jsonb jsonb = JsonbBuilder.create();

// Java → JSON
String json = jsonb.toJson(myObject);

// JSON → Java
MyClass obj = jsonb.fromJson(json, MyClass.class);

graph TD
    A["Java Object"] -->|toJson| B["JSON String"]
    B -->|fromJson| A

🎨 More Annotations

🦎 Polymorphic Type Handling: The Shape-Shifter

The Story

Imagine a magical pet that can be a dog, cat, or bird. When you save it to a file and open it later, how do you know which animal it is?

Polymorphic handling solves this! It stores a type hint so you know exactly what type to recreate.

The Challenge

abstract class Animal { }
class Dog extends Animal { String bark; }
class Cat extends Animal { String meow; }

List<Animal> pets = Arrays.asList(new Dog(), new Cat());

How does JSON know a Dog from a Cat when reading back?

Solutions

1. Type Property (Most Common)

Add a field that tells the type:

[
  {"@type": "Dog", "bark": "woof"},
  {"@type": "Cat", "meow": "purr"}
]

2. Custom Deserializer

public class AnimalDeserializer
    implements JsonbDeserializer<Animal> {

    @Override
    public Animal deserialize(JsonParser parser,
            DeserializationContext ctx, Type type) {

        JsonObject obj = parser.getObject();
        String animalType = obj.getString("@type");

        if ("Dog".equals(animalType)) {
            return ctx.deserialize(Dog.class, parser);
        } else {
            return ctx.deserialize(Cat.class, parser);
        }
    }
}

3. Using @JsonbTypeInfo (Jakarta EE 10+)

@JsonbTypeInfo(
    key = "@type",
    value = {
        @JsonbSubtype(alias = "dog", type = Dog.class),
        @JsonbSubtype(alias = "cat", type = Cat.class)
    }
)
public abstract class Animal { }

graph TD
    A["JSON with @type"] --> B{Check Type}
    B -->|dog| C["Create Dog"]
    B -->|cat| D["Create Cat"]
    B -->|bird| E["Create Bird"]

💡 Best Practices

1. Use a consistent type key (@type, _type, kind)
2. Keep type names simple (avoid full class names)
3. Register all subtypes for validation
4. Test round-trip (serialize then deserialize)

🎮 Putting It All Together

Here’s how all six tools work in a real REST API:

graph TD
    A["Client Request"] --> B{What to do?}
    B -->|Read big file| C["Streaming API"]
    B -->|Build response| D["Object Model"]
    B -->|Convert Java| E["JSON-B"]
    B -->|Find value| F["JSON Pointer"]
    B -->|Update part| G["JSON Patch"]
    B -->|Handle types| H["Polymorphic"]

Example: REST Endpoint

@Path("/users")
public class UserResource {

    @GET
    @Path("/{id}")
    public User getUser(@PathParam("id") long id) {
        // JSON-B auto-converts to JSON!
        return userService.find(id);
    }

    @PATCH
    @Path("/{id}")
    public User patchUser(@PathParam("id") long id,
                          JsonPatch patch) {
        JsonObject current = getCurrentAsJson(id);
        JsonObject updated = patch.apply(current);
        return saveFromJson(updated);
    }
}

🏆 Quick Summary

🚀 You Did It!

You now understand the six superpowers of JSON APIs in Jakarta EE! Whether you’re building tiny responses or handling massive data streams, you have the right tool for every job.

Remember:

• Small data? → Object Model
• Huge data? → Streaming
• Find something? → Pointer
• Change something? → Patch
• Convert objects? → JSON-B
• Multiple types? → Polymorphic

Now go build something amazing! 🎉