Skip to content

blackdoor/hate

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

69 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

hate

HATEOAS with HAL for Java. Create hypermedia APIs by easily serializing your Java models into HAL JSON.
More info in the wiki.

Gitter
Build Status
Codacy Badge
Codecov
Javadocs
Maven Central


Install with Maven

<dependencies>
  <dependency>
    <groupId>black.door</groupId>
    <artifactId>hate</artifactId>
    <version>v1r4t5</version>
  </dependency>
</dependencies>

Basic usage

Implement the HalResource interface in your model by implementing the location() and representationBuilder() methods. For example:

public class Order implements HalResource{

	private int id;
	private double total;
	private String currency;
	private String status;
	//note: Basket and Customer implement HalResource
	private Basket basket;
	private Customer customer;

	...

	@Override
	public URI location(){
		return new URI("/orders/" + id);
	}
	
	@Override
	public HalRepresentationBuilder representationBuilder() {
		return HalRepresentation.builder()
				.addProperty("total", total)
				.addProperty("currency", currency)
				.addProperty("status", status)
				.addLink("basket", basket)
				.addLink("customer", customer)
				.addLink("self", this);
	}
}	

Now to get the HalRepresentation of an Order object, simply do HalRepresentation hal = myOrder.asEmbedded(). You can serialize hal using hal.serialize() or with Jackson (eg. new ObjectMapper().writeValueAsString(hal))

The result would look like this:

{
  "total": 30,
  "currency": "USD",
  "status": "shipped",
  "_links": {
    "basket": {
      "href": "/baskets/97212"
    },
    "self": {
      "href": "/orders/123"
    },
    "customer": {
      "href": "/customers/7809"
    }
  }
}

Paginated Collections

To get a paginated HAL representation of a REST collection, simply use HalRepresentation.paginated(String, String, Stream, long, long).
For example:

Collection<Order> orders;

HalRepresentation hal = HalRepresentation.paginated(
	"orders", // the name of the resource collection
	"/orders", // the path the resource collection can be found at
	orders.stream(), // the resources
	pageNumber,
	pageSize // the number of resources per page
	).build();

Would give you something like this:

{
  "_links": {
    "next": {
      "href": "/orders?page=2"
    },
    "self": {
      "href": "/orders"
    }
  },
  "_embedded": {
    "orders": [
      {
        "total": 30,
        "currency": "USD",
        "status": "shipped",
        "_links": {
          "basket": {
            "href": "/baskets/97212"
          },
          "self": {
            "href": "/orders/123"
          },
          "customer": {
            "href": "/customers/7809"
          }
        }
      },
      {
        "total": 20,
        "currency": "USD",
        "status": "processing",
        "_links": {
          "basket": {
            "href": "/baskets/97213"
          },
          "self": {
            "href": "/orders/124"
          },
          "customer": {
            "href": "/customers/12369"
          }
        }
      }
    ]
  }
}