Implementing Spring HATEOAS linkbuilding

Question

I don't understand what I need to add to make my program become HATEOAS. I have Account .java, Post .java, Controllers and repositories . From some guides they add AccountResource and PostResource where they build links inside these classes. What is the difference between AccountResource and Account? Do I need both? If so, do I create a resource class for each normal class? I tried doing this and it didn't work at all. I have no idea what I'm doing anymore :( . I need some help understanding how to migrate from a normal REST to HATEOAS. What classes do I need to add?

public class Account {

//Account ID
@Id private String userId;

//General info
protected String firstName;
protected String lastName;
protected String username;
protected String email;
protected String password;
protected String birthDate;
protected String activities;
protected String uri;
private Set<Post> posts = new HashSet<>();
List<Account> friends = new ArrayList<Account>();

//Getter, constructor...



@RestController
public class AccountController {    

@Autowired
private AccountRepository accountRepository;

//Create account 
@RequestMapping(value="/accounts", method = RequestMethod.POST) 
public ResponseEntity<?> accountInsert(@RequestBody Account account) {

    account = new Account(account.getUri(), account.getUsername(), account.getFirstName(), account.getLastName(), account.getEmail(), account.getPassword(), account.getBirthDate(), account.getActivities(), account.getFriends());
    accountRepository.save(account);
    HttpHeaders httpHeaders = new HttpHeaders();
    Link forOneAccount = new AccountResource(account).getLink("self");
    httpHeaders.setLocation(URI.create(forOneAccount.getHref()));

    return new ResponseEntity<>(null, httpHeaders, HttpStatus.CREATED);
}



public class AccountResource extends ResourceSupport {

private Account account;

public AccountResource(Account account) {
    String username = account.getUsername();
    this.account = account;
    this.add(new Link(account.getUri(), "account-uri"));
    this.add(linkTo(AccountController.class, username).withRel("accounts"));
    this.add(linkTo(methodOn(AccountController.class, username).getUniqueAccount(account.getUserId())).withSelfRel());
}

public AccountResource() {

}

public Account getAccount() {
    return account;
}
}

Answer 1

Account , Post etc are your domain entities, while the *Resource are their representation exposed by your API to the external world.

Domain entities might be, for example, JPA Entities, containing all the metadata required for their persistency and relations with other entities. Even if they are not JPA entities, they are the internal representation used by your application business logic.

Resources contains the information for JSON Serialisation/Deserialisation, and no direct references to other resources.

Have a look at this sample project https://github.com/opencredo/spring-hateoas-sample and to the related blog post: Implementing HAL hypermedia REST API using Spring HATEOAS

It implements a simple, but not-so-trivial library API, with a Book - Author - Publisher domain.