The releases resource uses links inside the actual release representation, using …Url suffixes for the properties that contain URIs. It would be more idiomatic to rather move those to the _links section:
{
"…",
"_links" : {
"api-doc" : {
"href" : "…",
"type" : "text/html"
},
"reference-docs" : [
{ "href" : "…", "type" : "text/html" },
{ "href" : "…", "type" : "application/pdf" }
]
}
}Note, how that would allow us to advertise different formats for the reference documentation (it's currently only one link, which is fine for now) and also indicate that the api-doc link points to a browsable resource.
This would be a non-breaking change, as the links can be added without disturbing existing clients. The reference docs could incentivize using the HAL links though.
The
releasesresource uses links inside the actual release representation, using…Urlsuffixes for the properties that contain URIs. It would be more idiomatic to rather move those to the_linkssection:{ "…", "_links" : { "api-doc" : { "href" : "…", "type" : "text/html" }, "reference-docs" : [ { "href" : "…", "type" : "text/html" }, { "href" : "…", "type" : "application/pdf" } ] } }Note, how that would allow us to advertise different formats for the reference documentation (it's currently only one link, which is fine for now) and also indicate that the
api-doclink points to a browsable resource.This would be a non-breaking change, as the links can be added without disturbing existing clients. The reference docs could incentivize using the HAL links though.