Hypermedia with Spring Hateoas (Sandbox)

Little Sandbox to play around with Spring Hateoas.

Features:

• Hypermedia

  • HAL-FORMS, not just plain HAL (Hypertext Application Language)

  • Pagination with previous and next relations

  • URI Templates like /owners{?limit,offspring}

• Spring Hateoas

  • inkl. CURIEs (Compact URIs) which are used to scope custom rels because they are not registered IANA link relation types.

  • Forwarded header handling for applications behind a proxy where href Links should not point to localhost

• Hal-Explorer (after starting the backend visit http://localhost:8080)

Getting started

1. Use the .sdkmanrc java version: sdk env use

2. Start the backend: ./gradlew run

3. Explore via curl or httpie

Or at your own leasure:

• Run tests: ./gradlew test

Explore

Note	All Controller methods are explicitly annotated with produces = ["application/prs.hal-forms+json"], otherwise the server only answers with hal-forms if the client understands it, leaving you wondering where "_templates": […​] is in your json response.

The root gives us information where we can reach other items.

http GET localhost:8080/accounts/

{
    {
        "_embedded": {
            "accountDtoes": [
                {
                    "_id": "1",
                    "_links": {
                        "self": {
                            "href": "http://localhost:8080/accounts/1"
                        }
                    },
                    "balance": 1,
                    "name": "one"
                }
            ]
        }
    }
}

Notice that when we withdraw 9 credits we still have the option to withdraw more, but should the balance go to zero we can no longer withdraw and only deposit. Affordances at work :)

http POST localhost:8080/accounts/1/withdraw amount=9

{
    "balance": 1,
    "name": "one",
    "_templates": {
        "default": {
            "method": "POST",
            "properties": [
                {
                    "name": "amount",
                    "readOnly": true,
                    "type": "number"
                }
            ],
            "target": "http://localhost:8080/accounts/1/withdraw"
        },
        "deposit": {
            "method": "POST",
            "properties": [
                {
                    "name": "amount",
                    "readOnly": true,
                    "type": "number"
                }
            ],
            "target": "http://localhost:8080/accounts/1/deposit"
        }
    }
}

Further Reading

• Spring Hateoas Affordances Examples