RE: hydra:expects and hydra:returns

Hi Kuno,

Some more thoughts inline.

On Thursday, November 07, 2013 8:11 PM, Kuno Woudt wrote:
> Hello Markus,
> 
> On 11/06/2013 07:13 PM, Markus Lanthaler wrote:
> > Well, it depends on the point of view. A Web API client would like to
know
> > that the URLs changed. If it knows how to find the query the API to find
> > information about a specific Musicbrainz identifier (using IRI templates
> > e.g.) all is fine IMO.
> >
> > What practical problems do you see with this approach?
> 
> For clients who understand RDF, I don't see any problems -- as long as
> they get the same triples all should be fine.
> 
> I'm just worried that this will be confusing for developers who consume
> the response as JSON (without RDF).  When I rewrite my original
> example:
> 
> {
>      "@context": "https://example.com/context.json",
>      "@id": "https://example.com/musicvideos/murio.jsonld",
>      "foaf:PrimaryTopic": {
>          "@id": "mbrec:95dd147c-71ba-48b1-91f3-0bf2916e9ec4#_",
>          "@type": "mo:Signal",
>          "dbpedia:Director": {
>              "foaf:name": "Ray Cuts",
>              "sioct:microblog": {
>                  "@id": "https://twitter.com/RayCuts"
>              }
>          }
>      }
> }
> 
> A developer who wants to consume this will look at this response and
> will have to deal with two identifiers.  One for the document and one
> for the topic.  The document-about-a-topic vs topic distinction is
> something I would rather not burden my (non-RDF) clients with.

Understandable. I think that most of that problem can be mitigated by naming
properties differently (or modeling the data slightly differently. For
example, you could transform the document above to something like

{
  "@context": "https://example.com/context.json",
  "@id": "https://example.com/musicvideos/murio.jsonld",
  "about": "mbrec:95dd147c-71ba-48b1-91f3-0bf2916e9ec4"
  "director": {
    "name": "Ray Cuts",
    "microblog": "https://twitter.com/RayCuts"
  }
}

perhaps with a context that maps

{
  "about": { "@id": "foaf:isPrimaryTopicOf", "@type": "@id" },
  "director": "dbpedia:Director",
  "name": "foaf:name",
  "microblog": { "@id": "sioct:microblog", "@type": "@id" }
}

Perhaps even using a full absolute URL in "about" so that a JSON-only client
can easily follow that link. Alternatively, you could also just include the
MusicBrainz ID as string and create a specific property for that.


> If I didn't know about RDF and was designing this as a regular JSON API
> the response would look something like this:
> 
> {
>      "id": "95dd147c-71ba-48b1-91f3-0bf2916e9ec4",
>      "director": {
>          "name": "Ray Cuts",
>          "microblog": "https://twitter.com/RayCuts"
>      }
> }

Which is almost the same as the one above.


> Which is easy to understand.  The promise of JSON-LD is that this can be
> turned into linked data with minimal changes to the structure of the
> response.  I would like to stay as close to this as possible, while at
> the same time making things machine-readable.

Right, I find that crucial for the adoption of such APIs... but when it
comes to RESTful APIs, hypermedia is just as crucial and as such the URLs
are perhaps the most important "interfaces" to your data.


> Anyway, for now I will implement things as you suggest.  This is
> conversation is probably more productive when I have a running system
> to talk about instead of a bunch of hypotheticals :)

:-) I really enjoy these discussions but you are right. It's much easier to
experiment with something concrete at hand. Let us know when the first rough
version is ready.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Saturday, 9 November 2013 11:39:50 UTC