REST-API: Link/Multilink Properties

I'm in the process of drafting the documentation of the REST API.

Currently all Link and Multilink properties are displayed solely as the
ID, e.g. for a message we get:

{   
    "data": {
...
        "attributes": {
            "files": [
                "27"
            ], 
            "recipients": [
                "6",
                "7",
                "8",
                "11"
            ], 
            "author": "7",
...     
        }
    }
}

So we get recipients (Multilink to user) or files (Multilink to file) or
author (Link to user) as only a (list of) id.

John Rouillard has proposed (I think to me privately) to change this to,
e.g.

"recipients": [
    { "id": "6"
      "link": "http://...rest/data/user/6"
    }, ...
]

Before documenting the state of affairs and later changing it I tend to
fix this now and document it. Any objections?

Note that we also discussed that it might be interesting to add a
@verbose option that could display the key-property (or label property
if the class has no key), e.g.

"recipients": [
    { "id": "6"
      "link": "http://...rest/data/user/6"
      "username": "testuser"
    }, ...

Note that Johns original proposal was to always use a "name" property
but I think this would mislead as the key (or label-) property is not
always but often named "name" (e.g. for the status class).
I tend not to make showing names the default as this requires an
additional join (or worse as it's currently implemented a separate
database lookup for each and every linked/multilinked item).

What do you think about this change?

Ralf
-- 
Dr. Ralf Schlatterbeck                  Tel:   +43/2243/26465-16
Open Source Consulting                  www:   http://www.runtux.com
Reichergasse 131, A-3411 Weidling       email: [email protected]