W3C home > Mailing lists > Public > public-hydra@w3.org > December 2014

Local identifiers in IriTemplates

From: Dietrich Schulten <ds@escalon.de>
Date: Sat, 13 Dec 2014 11:06:27 +0100
Message-ID: <548C0FA3.7080407@escalon.de>
To: "public-hydra@w3.org" <public-hydra@w3.org>
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi,

Preparing the release of hydra-java with support for templates, I
wanted to ask for your opinions.

I understand templates as an equivalent to a GET http form, especially
since they have no facility to build a request body.

In Spring-Hateoas there is a Resources class which holds a collection
of items and allows to add links outside the item collection which
apply to the entire collection. This would be the typical place to
define a search template.

Currently hydra-java renders them like this, assuming that the user
has added the search template using a rel hydra:search:

{
    "@context":
    {
        "@vocab": "http://schema.org/",
        "hydra": "http://www.w3.org/ns/hydra/core#"
    },
    "@type": "hydra:Collection",
    "hydra:search": {
        "@type": "hydra:IriTemplate",
        "hydra:template": "http://localhost/events{?eventName}",
        "hydra:mapping": [
        {
            "@type": "hydra:IriTemplateMapping",
            "hydra:variable": "eventName",
            "hydra:required": true,
            "hydra:property": "http://schema.org/name"
        }]
    },
    "hydra:member": [
        {
          "@type": "Event",
          "@id": "http://localhost/events/1",
          "name": "Gang of Rhythm Tour"
          ...
        },
        { ... another event }
    ]
}

Is this correct RDF-wise? I am pretty sure it is, since I think I am
not adding any new properties to the hydra:Collection or other classes
which haven't been there in the first place.

But what if I wanted to add another template which does not fit so
nicely with schema.org?

Let's say I want to search by some database identifier in addition to
the search by name, so I make hydra:search an array and add another
IriTemplate:

"hydra:search":
 [
        {
            "@type": "hydra:IriTemplate",
            "hydra:template": "http://example.com/events/{eventId}",
            "hydra:mapping": [
            {
                "@type": "hydra:IriTemplateMapping",
                "hydra:variable": "eventId",
                "hydra:required": true,
                "hydra:property": "eventId" <-- what to put here?
            }]
        },
        {
            "@type": "hydra:IriTemplate",
            "hydra:template": "http://example.com/events{?eventName}",
            ... see above
        }
]

It seems quite common to make an internal identifier such as a
database ID part of a resource URI, and it is not far fetched to allow
a client to look up an item by that id.
For instance, think of an event location which maintains dozens of
events wants to review the event data of a particular event in the api
of an event platform.
Or, I have a case in mind where there are millions of customers so not
even a paged collection makes much sense for an API which allows
access to customer data. You really want to be able to say "get me
this particular customer by her customer id".
But what should I use as value of hydra:property in such a situation?

I could of course come up with a mini-vocabulary which describes that
id for my API. The reason I want to avoid that is the difficulty to
write a generic client which can handle this type of situation, if it
has to depend on vendor-specific vocabs.

Could we have a property like hydra:localIdentifier and describe it as
"an attribute which identifies a thing in its local context"? One
could use a hydra:label to give a hint to humans which interact with
the system.

Like this:

"@type": "hydra:IriTemplateMapping",
"hydra:variable": "eventId",
"hydra:required": true,
"hydra:property": "hydra:localIdentifier",
"hydra:label": "Enter your event number"

"@type": "hydra:IriTemplateMapping",
"hydra:variable": "loginId",
"hydra:required": true,
"hydra:property": "hydra:localIdentifier",
"hydra:label": "Enter your user name or email address"

A machine client could be programmed to start with some knowledge
about the context, for instance that it should use 4711 as a known
hydra:localIdentifier when navigating the API. Such a machine client
could be a client framework used by a mobile app, which operates in
the context of an authenticated user and can tell the client framework
about it. If we could also use hydra:returns on a template, it would
also be clear exactly what the localIdentifier identifies. That way I
could tell the machine client that it knows localIdentifiers both of
an Event and a Person which it should use when performing a ReviewAction.

Or is there a vocabulary out there which already has such a property?

Best regards,
Dietrich


- -- 
Dietrich Schulten
Escalon System-Entwicklung
Bubenhalde 10
74199 Untergruppenbach
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (MingW32)

iEYEARECAAYFAlSMD6IACgkQuKLNitGfiZNkRgCg4UPblYTY+jO3DwBlMGn6rqW5
Jq4An1Ok0tfxtAtoNe0thGBc/oQUyKdV
=UA3R
-----END PGP SIGNATURE-----
Received on Saturday, 13 December 2014 10:06:58 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 20:29:44 UTC