A HAL resource representation

This example incorporates the passive HAL mams-hello-one scenario from mams-guide. HAL adds links to a resource’s JSON representation, allowing a client to discover related URIs rather than construct every path itself.

Download the HAL example, extract it and run mvn clean compile astra:deploy.

This adaptation uses MAMS 2.4.1’s Java-Types library with its shared HAL converter. The original guide uses the separate mams.hal.Passive family; the current source retains that family as well. Using mams.javatypes.Passive here demonstrates JSON and HAL representations of the same resource without changing the resource management model:

import com.fasterxml.jackson.databind.JsonNode;

agent Main extends mams.javatypes.Passive {
    plan +!main(list args) {

        MAMSAgent::!setup();

        MAMSAgent::!created("base");


        mams.javatypes.Passive::!itemResource("hello", "Hello");
    }
}

The data class is the same public Hello class used in the other greeting examples. Request a HAL representation explicitly:

curl -i -H 'Accept: application/hal+json' \
  http://localhost:9000/main/hello

The negotiated response uses Content-Type: application/hal+json and Vary: Accept. At the audited commit, the shared HAL converter returns a links-and-metadata envelope: _links includes self, profile and parent links, and _embedded.body lists children. Its top-level name is agent metadata (main), not the Java object’s name field. The item data fields are not included in this HAL envelope. Read the actual item state as plain JSON with Accept: application/json. Some links are relative; resolve them against the response URI.

Replace its data using a JSON request body, while asking for HAL in the response:

curl -i -X PUT \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/hal+json' \
  -d '{"name":"Rem"}' \
  http://localhost:9000/main/hello

Repeat the HAL GET to inspect its links. To verify the changed item state, use:

curl -i -H 'Accept: application/json' \
  http://localhost:9000/main/hello

This returns {"name":"Rem"}. Content-Type describes the submitted data; Accept chooses the representation returned to the client. Choosing HAL changes the representation, not the passive resource management lifecycle.

For a representation containing both explicit resource identities and application state, see the optional Hydra/JSON-LD example introduced in MAMS 2.0.0.