HATEOAS links with PUT/POST

Question

What would be the best way to represent a HATEOAS link for a POST/PUT/PATCH on a resource? These operations have payload but we won\'t

Answer 1

Links are comprised of two elements: href and rel. The href contains the explicit URL to locate a resource. The rel identifies the relationship between the current resource and the link's resource. The rel should be used to determine what HTTP method is acceptable and how the link should be used.

The following is a quote from RESTful Web Services Cookbook section 5.4:

A link relation type conveys the role or purpose of a link. Once clients and servers agree on the meaning of these types, clients can find and use URIs from links.

For example, edit is a standard link relation that has explicit details including details around using GET, PUT, POST, DELETE.

Link relations can be extended and you can add your own.

Answer 2

These operations have payload but we won't have an option to represent the payload in HATEOAS link as they aren't predetermined and can be heavy?

The usual answer is that you document the operations in your description of the media types that you are using for your representations.

One reference to consider is Atom Syndication/Atom Pub. The basic idea being that specification of the media-type tells you how to interpret the document, including the interpretation of the link relations.

See also Fielding, 2008

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type

As a rule, PUT and PATCH should be pretty straight forward - these are remote authoring methods; the request-body of a PUT is normally just an edited version of the representation provided by GET, and PATCH is just a different way of describing the edits (typically using one of the media-types described by the Accept-Patch header).

POST is the hard one - because POST semantics have very loose constraints, there are a lot of degrees of freedom. If you can't describe the additional constraints in line, then you have to lean harder on your definition of the media type.