adding HTTP method to Spring HATEOAS links

Question

I am wondering if it is possible to add HTTP method to the links created with Spring HATEOAS. I would like the link to look something like:

{
    "href":http://localhost:8080/admin/users",
    "rel": "add",
    "method": "POST"
}

{
    "href":http://localhost:8080/admin/users/john",
    "rel": "remove",
    "method": "DELETE"
}

I couldn't find anything which would allow me to add "method" to the link.

Number

Answer 1

That wouldn't make sense. The href specifies the address of some resource, and the rel tells how it's related to the current resource. The HTTP method indicates what the client wants to do to it, which isn't a part of the relationship between the two.

In your example, the "remove" relation doesn't make sense: HTTP specifies the DELETE verb, and the semantics of

DELETE http://localhost:8080/admin/users/john

are already known. Similarly, POST creates a new resource, so specifying /admin/users is sufficient for a client to list the users (with GET) or add a new user (with POST).

Aramen

PayPal uses this format: PayPal REST API – Number

@Number It appears that they do, but it still doesn't make sense. The methods (which aren't all even real) correspond to the existing HTTP semantics, and so they're just a sort of bizarre comment. – Aramen

I have to object. Who says that the resource can be deleted? remove makes this fact explicit. If it is missing then the client can act accordingly instead of trying and getting an error. Or imagine rel=payment. Can you pay John by POSTing to it or retrieve information about his payment by GETting it? – Infare

@zeroflagL If you understand the semantics of the data type (e.g., the contents of a JSON object), then you already know whether it's sensible to attempt deleting or creating records. – Aramen

@chrylis JSON alone may not be sufficient. What if I have a default user (root) which cannot be deleted. In that case want to let the consumer of my API know by ommiting the link with the DELETE verb whereas all other user will have that link. – Number

@Number Then that's a property of the resource, not the relation, and either it should be marked "no-delete" in the representation or the server should just return a suitable 400 and not worry about specifying every possible contingency explicitly. – Aramen

In lack of time I want to quote Wikipedia: link relations are one of the foundations of HATEOAS as they allow the user agent to understand the meaning of the available state transitions. That's right: state transitions. And that's what business applications are all about. If you only make CRUD stuff, then, yes, you don't need that fancy relations. BTW: There is no standard telling you what valid relations are. – Infare

@zeroflagL In fact, there are a number of standard relations (from HTML and other sources), but your response is irrelevant to adding methods to link metadata. – Aramen

Standard relations and a standard of what qualifies a relation as valid in general are two different things. And it is relevant. Although I have to admit that I personally wouldn't add methods. – Infare

Answer 2

You should use the relation "edit".

In the section (11.1) from the Atom Pub RFC (https://www.rfc-editor.org/rfc/rfc5023) which defines that you can send PUT/DELETE/GET requests to this URI of the edit relation.

Garey

Answer 3

Consider implementing a HTTP OPTIONS at the URIs you've specified. This would respond with the valid options for that resource. It's not often done, but for me OPTIONS is a perfect way to help clients understand what is permitted.

Excellent blog post here: http://zacstewart.com/2012/04/14/http-options-method.html

Chromomere

Answer 4

Spring HATEOAS appears to support affordances now which allows you to build hypermedia that affords operations using HAL-FORMS. This would have allowed the OP to achieve something similar to what was requested albeit with a different (and more complex [flexible?]) schema.

https://github.com/spring-projects/spring-hateoas-examples/tree/master/affordances

Intervention

Answer 5

I have designed REST APIs based on the Richardson model; http://martinfowler.com/articles/richardsonMaturityModel.html

All endpoints returned the "allowed" links with an HTTP method. This design approach allowed the consumer to know the HTTP method to use, rather than calculate what method to use. This was useful since some operations used POST or PUT. POST is used to create a resource or change the state of a resource. PUT was used to update an existing resource and delete to remove a resource.

Including the HTTP method in a link is a powerful mechanism that enables the consumer of the API to know how to call the API.

Clavicle

Are you sure that your answer solves OP question? I can't see anything related with Spring framework in it. – Frannie

Answer 6

A link relation alone should be able to instruct clients how to use the link so I think having the method parameter in the link would be redundant. The definition of the link relation should have the details of what are the acceptable HTTP methods.

Also, I think the method parameter approach makes your system more confusing and more error-prone.

Let's say you have a link relation do-something which was initially designed to only allow for POSTs. Then the creator of do-something wishes to change that characteristic and switch to PUTs only. Having the method parameter in the links makes you become susceptible to an inconsistency between the "source of truth" (the link relation definition) and the servers that provide the links.

Trapper