vnd.error
vnd.error copied to clipboard
blongden
HAL Compliance & Generla Normalization
error isn't IANA (http://www.iana.org/assignments/link-relations/link-relations.xhtml) so it really should be prefixed.
Also consider not having the multiple embedding be errors : [] as if this doc is interpreted as HAL it doesn't make much sense. Each error resource is an error of the parent document. each one is not an errors. It's tempting to name it errors because of the plurality, but condier it has say html encoded:
<head>
<link rel="error" href=""/>
<link rel="error" href=""/>
</head>
or embedded
<body>
<span class="error">Message</span>
<span class="error">Message</span>
</body>
in hal the _embedded key is the link relationship of each entry, not all entries as a whole
I disagree.
You don't write code like this:
List<Employee> employee = new ArrayList<>();
...and call the entire list employee simply because a single item is a employee.
No, you probably write this:
List<Employee> employees = new ArrayList<>();
So if the embedded list of VndError objects is an array, what is wrong with the key being errors?
nothing too wrong..just depends what the link relationship dereferences to. just like item vs items...you are linking to an individual error with each link..not a collection of errors (which then would have links to individual error items which unless your "errors" has some useful properties really would be rather redundant). each error item is an error of the parent..not a collection of errors.
it'd be like saying 1 of your sisters was your sisters not your sister.
now if you want to group them as a whole collection.
lots of people don't get that the rel is an attribute of the link...not a field on the resource when looking at hal/json. hal/json just indexes all links by rel for easier access..something not possible in hal/html.
ie when you read:
_links : { car : { href: "x"} }
you should think
a resource with a link of {rel: "car", href:"x"}
check the link registry https://www.iana.org/assignments/link-relations/link-relations.xhtml almost all are singular...for example author. there's not an authors...just multiple author links.
Are we talking about the same thing?
I saw:
{
"total": 2,
"_embedded": {
"errors": [
{
"message": "\"username\" field validation failed",
"logref": 50,
"_links": {
"help": {
"href": "http://.../"
}
}
},
{
"message": "\"postcode\" field validation failed",
"logref": 55,
"_links": {
"help": {
"href": "http://.../"
}
}
}
]
}
}
...and observed an array [ ... ] structure assigned to errors.
In which example is errors referencing a single-item? The only single-item error I spotted was the first, and in that situation, there is no usage of _embedded.
yeah you're just interpreting it as json and not as hal/json.
the resource you pasted interpreted as hal/json indicates two prefetched (hypertext cache pattern) links with relationship errors
first errors link prefetched is
{
"message": "\"username\" field validation failed",
"logref": 50,
"_links": {
"help": {
"href": "http://.../"
}
}
}
second errors link prefetched is
{
"message": "\"postcode\" field validation failed",
"logref": 55,
"_links": {
"help": {
"href": "http://.../"
}
}
}
neither is an errors...both are an error. so error would be the more appropriate key. it's nuanced and tricky.
one way to see it better...here's the https://github.com/kevinswiber/siren version of your document
{
properties : {
"total": 2
},
"entities": [
{
"rel": [ "errors" ],
"properties" : {
"message": "\"username\" field validation failed",
"logref": 50
},
"links": [
{ rel: "help", "href": "http://.../"}
]
}
},
{
"rel": [ "errors" ],
"properties" : {
"message": "\"username\" field validation failed",
"logref": 55
},
"links": [
{ rel: "help", "href": "http://.../"}
]
}
]
}
the rel of errors is more apparently strange in siren (mason too). each prefetched/embedded entity is clearly an error not an errors hal/json with is very useful indexing of hypermedia controls by their rel kinda confuses the plurality issue. equally...the omission of the _links in your example (which is perfectly valid) confuses the issue a bit...since rel is an attribute of a link..but clearly is not an attribute of a prefetched resource....in fact there's quite a few weaknesses in HAL/JSON's prefetching serialization mechanism..for example the inability to declare prefetches by the links name attribute.
i go into a lot deeper examples of items vs item (equivalent to this error vs errors) at https://stackoverflow.com/a/44739243/442773
Intriguing.
That’s a level of HAL I’ve never read before. Granted, finding experts on HAL and hypermedia isn’t easy.
Thanks. This may impact some of our design choices in Spring HATEOAS.
yeah HATEOAS' auto rel thing gets it wrong sometimes (and it's got other issues https://github.com/spring-projects/spring-hateoas/issues/175 which you closed..very unfortunate limitation)...but IIRC it got it right on the Page resource (things are embedded as item vs items).
i had to stop using it cause of how it tries to make json that looks like hal/json and not a hyper resource that is serialized as hal/json. the affordances are a step in the right direction.