search

w3c / w3c-api

The W3C API
https://w3c.github.io/w3c-api/
214 stars 92 forks source link

Inconsistent use of “name” and “title” #30

Closed tripu closed 9 years ago

tripu commented 9 years ago

In the API, field names name and title seem to be used indistinctively.

An example: in the data returned by https://api-test.w3.org/domains/41381?embed=true, the name of the domain is inside name; but the name of the domain lead is inside _links.lead.title (not _links.lead.name).

Another example: in https://api-test.w3.org/users/ggdj8tciu9kwwc4o4ww888ggkwok0c8?embed=true, the name of the user is inside name; but in https://api-test.w3.org/users/ggdj8tciu9kwwc4o4ww888ggkwok0c8/specifications?embed=true, the name of the first spec is inside _embedded.specifications[0].title (not _embedded.specifications[0].name).

A consistent choice would help Apiary and other HATEOAS clients. Right now, Apiary has to check both fields when it expects a field to contain “the name of something”.

I suggest we always use name; I think it's the most generic term, and it's OK for people, groups, institutions, documents, etc.

vivienlacourba commented 9 years ago

Hi @tripu, for links the name and title properties have different meanings and are used correctly in the above examples. Note that there is a difference between "name" being used as a resource property and "name" being used in the context of a HAL link object.

See the "5.5. name" and "5.7. title" properties of Link objects in HAL.

tripu commented 9 years ago

Thanks, @vivienlacourba. I think I get it.

I guess for every {title, href}, I should request that href, and from THAT result, use the field "name"...

Assigning this pseudo-issue to myself to double-check that that is all I need in Apiary; will follow up.