hateoas

Name: hateoas
Author: rrezartprebreza

174stars33forks

How to install hateoas?

rrezartprebreza/spring-boot-skills/hateoas

$npx -y skills add rrezartprebreza/spring-boot-skills --skill hateoas

Installs into the current project.

Summary

Use when adding hypermedia links to REST responses, building self-describing APIs, or implementing Spring HATEOAS. Use when you see EntityModel, CollectionModel, or RepresentationModel in the project.

Files · 1

View on GitHub

SKILL.md

1	# Spring HATEOAS
2
3	## Dependency
4
5	```xml
6	<dependency>
7	<groupId>org.springframework.boot</groupId>
8	<artifactId>spring-boot-starter-hateoas</artifactId>
9	</dependency>
10	```
11
12	## When to Add Links
13
14	- `self` — always, on every resource response
15	- `collection` — link back to the list endpoint
16	- `related resources` — when a client commonly needs to navigate to them
17	- `actions` — links to state transitions (e.g., `cancel`, `ship`) when valid for current state
18
19	## Resource Model
20
21	```java
22	public class OrderModel extends RepresentationModel<OrderModel> {
23	private final UUID id;
24	private final String status;
25	private final String customerEmail;
26	private final Instant createdAt;
27
28	// Static factory with links
29	public static OrderModel from(Order order) {
30	OrderModel model = new OrderModel(
31	order.getId(), order.getStatus().name(),
32	order.getCustomerEmail(), order.getCreatedAt()
33	);
34
35	// Self link — always
36	model.add(linkTo(methodOn(OrderController.class).getById(order.getId())).withSelfRel());
37
38	// Collection link
39	model.add(linkTo(methodOn(OrderController.class).list(null)).withRel("orders"));
40
41	// Conditional action links based on state
42	if (order.getStatus() == OrderStatus.PENDING) {
43	model.add(linkTo(methodOn(OrderController.class)
44	.cancelOrder(order.getId())).withRel("cancel"));
45	}
46	if (order.getStatus() == OrderStatus.PROCESSING) {
47	model.add(linkTo(methodOn(OrderController.class)
48	.shipOrder(order.getId())).withRel("ship"));
49	}
50
51	return model;
52	}
53	}
54	```
55
56	## Controller
57
58	```java
59	@RestController
60	@RequestMapping("/api/v1/orders")
61	public class OrderController {
62
63	@GetMapping("/{id}")
64	public ResponseEntity<OrderModel> getById(@PathVariable UUID id) {
65	Order order = orderService.findById(id);
66	return ResponseEntity.ok(OrderModel.from(order));
67	}
68
69	@GetMapping
70	public ResponseEntity<CollectionModel<OrderModel>> list(Pageable pageable) {
71	Page<Order> orders = orderService.findAll(pageable);
72
73	List<OrderModel> models = orders.getContent().stream()
74	.map(OrderModel::from)
75	.toList();
76
77	CollectionModel<OrderModel> collection = CollectionModel.of(models,
78	linkTo(methodOn(OrderController.class).list(pageable)).withSelfRel()
79	);
80
81	// Pagination links
82	if (orders.hasNext()) {
83	collection.add(linkTo(methodOn(OrderController.class)
84	.list(pageable.next())).withRel(IanaLinkRelations.NEXT));
85	}
86	if (orders.hasPrevious()) {
87	collection.add(linkTo(methodOn(OrderController.class)
88	.list(pageable.previousOrFirst())).withRel(IanaLinkRelations.PREV));
89	}
90
91	return ResponseEntity.ok(collection);
92	}
93	}
94	```
95
96	## Response Shape
97
98	```json
99	{
100	"id": "550e8400-e29b-41d4-a716-446655440000",
101	"status": "PENDING",
102	"customerEmail": "user@example.com",
103	"_links": {
104	"self": { "href": "http://api.example.com/api/v1/orders/550e8400" },
105	"orders": { "href": "http://api.example.com/api/v1/orders" },
106	"cancel": { "href": "http://api.example.com/api/v1/orders/550e8400/cancel" }
107	}
108	}
109	```
110
111	## RepresentationModelAssembler Pattern
112	- Spring's recommended way to build HATEOAS models from entities
113	- Implements `RepresentationModelAssembler<Entity, Model>` — reusable across controllers
114	- Inject the assembler into controllers instead of calling `Model.from()` directly
115
116	```java
117	@Component
118	public class OrderModelAssembler implements RepresentationModelAssembler<Order, EntityModel<OrderResponse>> {
119
120	@Override
121	public EntityModel<OrderResponse> toModel(Order order) {
122	EntityModel<OrderResponse> model = EntityModel.of(OrderResponse.from(order),
123	linkTo(methodOn(OrderController.class).getById(order.getId())).withSelfRel(),
124	linkTo(methodOn(OrderController.class).list(null)).withRel("orders"));
125
126	if (order.getStatus() == OrderStatus.PENDING) {
127	model.add(linkTo(methodOn(OrderController.class)
128	.cancelOrder(order.getId())).withRel("cancel"));
129	}
130	return model;
131	}
132	}
133	```
134
135	## PagedModel for Paginated Collections
136	- Use `PagedResourcesAssembler` for automatic pagination links (first, prev, next, last)
137	- Inject `PagedResourcesAssembler<Order>` into controllers — Spring creates it automatically
138
139	```java
140	@GetMapping
141	public ResponseEntity<PagedModel<EntityModel<OrderResponse>>> list(
142	Pageable pageable, PagedResourcesAssembler<Order> pagedAssembler) {
143	Page<Order> orders = orderService.findAll(pageable);
144	PagedModel<EntityModel<OrderResponse>> pagedModel =
145	paged

People who liked this also viewed

6 picks

Type

hateoas

174stars33forks

View on GitHub

How to install hateoas?

rrezartprebreza/spring-boot-skills/hateoas

$npx -y skills add rrezartprebreza/spring-boot-skills --skill hateoas

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Spring HATEOAS
2
3	## Dependency
4
5	```xml
6	<dependency>
7	<groupId>org.springframework.boot</groupId>
8	<artifactId>spring-boot-starter-hateoas</artifactId>
9	</dependency>
10	```
11
12	## When to Add Links
13
14	- `self` — always, on every resource response
15	- `collection` — link back to the list endpoint
16	- `related resources` — when a client commonly needs to navigate to them
17	- `actions` — links to state transitions (e.g., `cancel`, `ship`) when valid for current state
18
19	## Resource Model
20
21	```java
22	public class OrderModel extends RepresentationModel<OrderModel> {
23	private final UUID id;
24	private final String status;
25	private final String customerEmail;
26	private final Instant createdAt;
27
28	// Static factory with links
29	public static OrderModel from(Order order) {
30	OrderModel model = new OrderModel(
31	order.getId(), order.getStatus().name(),
32	order.getCustomerEmail(), order.getCreatedAt()
33	);
34
35	// Self link — always
36	model.add(linkTo(methodOn(OrderController.class).getById(order.getId())).withSelfRel());
37
38	// Collection link
39	model.add(linkTo(methodOn(OrderController.class).list(null)).withRel("orders"));
40
41	// Conditional action links based on state
42	if (order.getStatus() == OrderStatus.PENDING) {
43	model.add(linkTo(methodOn(OrderController.class)
44	.cancelOrder(order.getId())).withRel("cancel"));
45	}
46	if (order.getStatus() == OrderStatus.PROCESSING) {
47	model.add(linkTo(methodOn(OrderController.class)
48	.shipOrder(order.getId())).withRel("ship"));
49	}
50
51	return model;
52	}
53	}
54	```
55
56	## Controller
57
58	```java
59	@RestController
60	@RequestMapping("/api/v1/orders")
61	public class OrderController {
62
63	@GetMapping("/{id}")
64	public ResponseEntity<OrderModel> getById(@PathVariable UUID id) {
65	Order order = orderService.findById(id);
66	return ResponseEntity.ok(OrderModel.from(order));
67	}
68
69	@GetMapping
70	public ResponseEntity<CollectionModel<OrderModel>> list(Pageable pageable) {
71	Page<Order> orders = orderService.findAll(pageable);
72
73	List<OrderModel> models = orders.getContent().stream()
74	.map(OrderModel::from)
75	.toList();
76
77	CollectionModel<OrderModel> collection = CollectionModel.of(models,
78	linkTo(methodOn(OrderController.class).list(pageable)).withSelfRel()
79	);
80
81	// Pagination links
82	if (orders.hasNext()) {
83	collection.add(linkTo(methodOn(OrderController.class)
84	.list(pageable.next())).withRel(IanaLinkRelations.NEXT));
85	}
86	if (orders.hasPrevious()) {
87	collection.add(linkTo(methodOn(OrderController.class)
88	.list(pageable.previousOrFirst())).withRel(IanaLinkRelations.PREV));
89	}
90
91	return ResponseEntity.ok(collection);
92	}
93	}
94	```
95
96	## Response Shape
97
98	```json
99	{
100	"id": "550e8400-e29b-41d4-a716-446655440000",
101	"status": "PENDING",
102	"customerEmail": "user@example.com",
103	"_links": {
104	"self": { "href": "http://api.example.com/api/v1/orders/550e8400" },
105	"orders": { "href": "http://api.example.com/api/v1/orders" },
106	"cancel": { "href": "http://api.example.com/api/v1/orders/550e8400/cancel" }
107	}
108	}
109	```
110
111	## RepresentationModelAssembler Pattern
112	- Spring's recommended way to build HATEOAS models from entities
113	- Implements `RepresentationModelAssembler<Entity, Model>` — reusable across controllers
114	- Inject the assembler into controllers instead of calling `Model.from()` directly
115
116	```java
117	@Component
118	public class OrderModelAssembler implements RepresentationModelAssembler<Order, EntityModel<OrderResponse>> {
119
120	@Override
121	public EntityModel<OrderResponse> toModel(Order order) {
122	EntityModel<OrderResponse> model = EntityModel.of(OrderResponse.from(order),
123	linkTo(methodOn(OrderController.class).getById(order.getId())).withSelfRel(),
124	linkTo(methodOn(OrderController.class).list(null)).withRel("orders"));
125
126	if (order.getStatus() == OrderStatus.PENDING) {
127	model.add(linkTo(methodOn(OrderController.class)
128	.cancelOrder(order.getId())).withRel("cancel"));
129	}
130	return model;
131	}
132	}
133	```
134
135	## PagedModel for Paginated Collections
136	- Use `PagedResourcesAssembler` for automatic pagination links (first, prev, next, last)
137	- Inject `PagedResourcesAssembler<Order>` into controllers — Spring creates it automatically
138
139	```java
140	@GetMapping
141	public ResponseEntity<PagedModel<EntityModel<OrderResponse>>> list(
142	Pageable pageable, PagedResourcesAssembler<Order> pagedAssembler) {
143	Page<Order> orders = orderService.findAll(pageable);
144	PagedModel<EntityModel<OrderResponse>> pagedModel =
145	paged

People who liked this also viewed

6 picks

Type