Master-detail representation in Json-LD

Question

On forhand : sorry if I misunderstood hypermedia or Restfull concepts : it's a work in progress...)

I try to figure out hypermedia and hydra (http://www.markus-lanthaler.com/hydra), and have some questions about returning information to the client before designing my api.

say I have a webshop located at www.myshop.com

a HTTP GET to the root could return (for example) a list of resources represented as link (in a json-ld document):

...
"@id": "/api",
"products" : "www.myshop.com/api/products",
"customers":"www.myshop.com/api/customers"
...

First question on hydra, how could I add actions here ? it seems the client needs to load another document before the load of application. I mean the potential actions are not in the docuemnt retrieved from www.myshop.com/api Or do I miss something?

---

Then going further, I've stated that products is a hydra:Link so that the client could follow that link (interact with it) with a HTTP GET and retrieve a list of products. that will be a list like this :

....
{
  "@id": "/api/products/123",
  "@type": "vocab:Product"
},
{
  "@id": "/api/products/124",
  "@type": "vocab:Product"
},
....

here the client receives a list of product (That could be a paged collection). But if the client wants to display it to the user, let's say a table with [product Id, price, name] (not all Product's properties)

Second Question : How could I do that without the client sending a request to the server for each product, but still provide the link to get the product's detailed information,(or even here having four link : one for getting the detailed information, one for Delete and one for sharing it with a friend and a last one to add it to a Basket) ?

In fact I have difficulties to figure out how hydra is coming into play by not having Links in the document itself? I think that Hal uses this approach to having links in the document itself (if I am right) and I try to find how hydra does this link...

regards

Answer 1

A bit late but I'll nevertheless try to answer your questions Cedric.

say I have a webshop located at www.myshop.com

a HTTP GET to the root could return (for example) a list of resources represented as link (in a json-ld document):

 ... "@id": "/api",
 "products" : "www.myshop.com/api/products",
 "customers":"www.myshop.com/api/customers" ...

First question on hydra, how could I add actions here ? it seems the client needs to load another document before the load of application. I mean the potential actions are not in the docuemnt retrieved from www.myshop.com/api Or do I miss something?

You basically have two options here: 1) embed the operations directly in the response or 2) attach the operations to the properties (products, customers) instead.

Approach 1) would look somewhat like this:

...
"@id": "/api",
"products" : {
  "@id": "http://www.myshop.com/api/products",
  "operation": {
    "@type": "Operation",
    "method": "POST",
    "expects": "Product"
  }
}
...

While approach 2) would attach the same operation to the products property in the referenced Hydra ApiDocumentation:

...
"@id": "...products",
"supportedOperation": {
  "@type": "Operation",
  "method": "POST",
  "expects": "Product"
}
...

Please note that in 1) I used operation while in 2) I used supportedOperation. Also, you should use a more specific type than Operation.

Regarding your second question:

with a HTTP GET and retrieve a list of products. that will be a list like this :

....
{
  "@id": "/api/products/123",
  "@type": "vocab:Product"
},
{
  "@id": "/api/products/124",
  "@type": "vocab:Product"
},
....

here the client receives a list of product (That could be a paged collection). But if the client wants to display it to the user, let's say a table with [product Id, price, name] (not all Product's properties)

Second Question: How could I do that without the client sending a request to the server for each product, but still provide the link to get the product's detailed information,(or even here having four link : one for getting the detailed information, one for Delete and one for sharing it with a friend and a last one to add it to a Basket) ?

You can add as much information (including links) as you want directly in the collection.

....
{
  "@id": "/api/products/123",
  "@type": "vocab:Product",
  "name": "Product 123",
  "price": "9.99"
},
{
  "@id": "/api/products/124",
  "@type": "vocab:Product",
  "name": "Product 124",
  "price": "19.99"
},
....

That way, a client only needs to dereference an item if the collection doesn't contain that required information.

In fact I have difficulties to figure out how hydra is coming into play by not having Links in the document itself?

Of course you do have links in the document as well. Links are just properties whose values happen to be URLs (objects with an @id property unless you set the property's type to @id in the context to get rid of that) instead of treating them specially.

Answer 2

note: The Hydra part of the answers I am not so sure, the JSON-LD and REST are okay I think.

You can use @base and relative IRIs by JSON-LD, or you can define namespaces in the @context, so after that you can use relative IRIs as ns:relativeIRI. Each one is better than returning the full IRI. (It is easier to parse the results with a general JSON-LD parser on client side, instead of a simple JSON parser.)

You can define your own @vocab using the Hydra vocab, or you can add "action" definitions in the @context. If you want to "add actions" you have to use hydra:Operation sub-classes in your vocab. Something like this (but I am not a Hydra expert):

{
    "@id": "vocab:ProductList",
    //...
    "hydra:supportedOperations": [
        {
            "@type": "hydra:CreateResourceOperation",
            "method": "POST",
            "expects": "vocab:Product"
        }
        //...
    ]
}

In general by REST, if you need the same resource with fewer properties, then you have to add a new IRI for that resource, e.g.: /myresource?fewer=1. For example in your case: /api/products/?fields="id, price, name" is okay.

By Hydra you have 2 choices if you want multiple links; you can add a new hydra:Link as a property, or you can add a new hydra:Operation as a supportedOperation with method: GET. I guess get operations are for something like search which has an user input, but if you don't want to add a new property for each link, I think you have no other option.

Actually Hydra does have link and operation support. Maybe it is not clear, but JSON-LD is an RDF format, you can define RDF triples in that. So the IRIs you used for example by "customers":"www.myshop.com/api/customers" are just resource identifiers and not links. A link should have IRI, title, method(GET), language, content-type, iana:relation, etc... so it is not possible to describe a link you can follow with just a single IRI (resource identifier). By processing a REST resource a client should never check the IRI structure to know how to display what it got from you. You have to check the other properties of the links, especially iana:relations or by Hydra maybe operation type to do that. So for example in your case www.myshop.com/api/dav8ufg723udvbquacvd723fudvg is a perfectly valid IRI for the list of the customers. We use nice IRIs only because it is easier to configure generate them on server side, and configure a router for them.

Please check the Hydra vocab before further questions. As you can see a Class can have supportedOperations and supportedProperties which are both collections. A Link is a Property sub-class which can have a single Operation. By collections I think you have to use the Collection class, in which member contains the items of the collection... Be aware that by JSON-LD there is no difference by defining a single item or multiple items with the same type. In the context you have to define only the type, and the value of the property can contain both a single item or an array of items... If you want some constraints about that I guess you have to add some OWL triples, and a validator which checks the values using them.