HATEOS with HAL and links to embedded ressources

Question

I think the answer to this question is great because it explains a lot about HAL: How to handle nested resources with JSON HAL?

However it does not fully answer the question (at least for me). Assuming we have a /employees resource that returns a list of all employees. I want the employees embedded but just with some basic information (not the full employee). This is OK according to the above answer and the spec. But how would my link look like?

So what would _links look like? Lets simplify the example. Assume there is no paging:

GET /employees

{
    "_links": {
        "self": { "href": "/employees" },
        "employees" { "href": "/employees/{id}", "templated": "true" }
    },
    "_embedded": {
        "employees": [{
            "id": "1",
            "fullname": "bla bli",
            "_links": { ... }
        },
        {
            "id": "2",
            "fullname": "djsjsdj",
            "_links": { ... }
        }]
    }
}

Does the templated "emloyees" URL make sense or would this be a case where you would not use any entry in _links? And if the URL is OK: is it necessary that the template parameter (here "id" does match the attribute in the embedded employee objects?

Answer 1

My heuristic is to consider the analogs in HTML - if it's OK for a web page, then it will also be OK for HAL.

"employees" { "href": "/employees/{id}", "templated": "true" }

What's the HTML analog? It's a form with a GET action. Can we have a form with a get action on a web page that also has digests of the information that will be reached via the form? Of course. So it must be fine here.

is it necessary that the template parameter (here "id") does match the attribute in the embedded employee objects?

I don't think it's necessary (the machines don't really care), but it's going to make life easier for the humans, and that alone has value.

Imagine, if you will, reading the documentation of a schema, and discovering that the same semantic concept (an identifier for an employee) has two different names with unrelated spellings. I would guess that would (a) introduce avoidable errors in the documentation when authors get confused about which spelling context they are in and (b) that's the sort of inconsistency that would make me suspicious of the quality of the specification as a whole.

But it's not impossible to have tradeoffs, and other benefits that outweigh these liabilities.