Complex properties that are not subresource in Hal,Siren etc.

[Dmitry Pavlov]

Hi,

I can't find any examples with this, or any official information in specs, if complex properties are allowed.

I performed tests with the following example template, adapted to different formats:

{

"name" : "Frame for a puzzle",

"outer_size" : { width : 67, height : 50.5, unit : "cm"}

"inner_size" : {width : 60, height: 40.5, unit : "cm"}

}

Hal browser handled it successfully as well as siren browser.

Is it correct behaviour or just a bug in browsers?

What's your opinion about using such complex properties? It's ok for some cases or I should better include them as embedded object without links?

P.S. let me know if I should ask this in corresponding format discussion groups, instead of this list

--
Regards,

Dmitry Pavlov

[Mike Kelly]

It depends, but complex properties are usually smell that there's a sub-resource that can be extracted.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

--
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

[Dmitry Pavlov]

I most cases I agree, but I can imaging some cases when we have entity that can have some complex properties and they are useless as a separate.

Of course I can include them as the embedded resources, identified by urls, and would not make assumptions if they are usefull or not. 

BTW how the client be sure that embedded ones are returned in full and he should not make additional requests? Specify it in user documentation or state that resource is full if there is not link with special relation?

P.S. HAL browser and siren browser perfectly handle embedded objects without links section. Siren event classifyes embedded resources by it: if it has links then it "link" else it's "embedded"

С уважением,
Дмитрий Павлов

[Kevin Swiber]

Complex properties are fine.  In the Domain-Driven Design world, we use different terminology for "objects with identity" and "objects without identity" (simplified).  The latter usually takes the form of a "complex property."  The former, applied to APIs, would take the form of an addressable resource.  An Address is often a good example.  In some domains, an Address might be significant and have identity.  In others, it might be included as a property of another object, such as a Customer.

Siren supports this in an upfront manner, as it has taken much influence from Domain-Driven Design (see: use of the term Entity).  You can certainly model it in HAL, as well.

Embedded representations may not have the same elements as their full counterparts.  This is often communicated via documentation.  Classes in Siren can also be used to help give clients a sense of what "view" they're receiving.  Think of a list view item representation in a UI; it often differs from the full representation.

Kevin Swiber

Projects: https://github.com/kevinswiber
Twitter: @kevinswiber

[Alex Soto]

I'd agree Kevin and Mike are both correct. I lean towards the idea that if the 'complex property' can be addressable as a resource (/resource/:id) in your api, then it should be a sub-resource.  If not, then it's probably ok, but if you find that you keep adding complexity to the property (more properties, deeper nested objects) then it's probably a stand-alone resource.

One area I've seen this happen is you want certain properties of the sub-resource, but don't want to embed the full resource or to make another request for the sub-resource. In Siren you could make it an embedded sub-entity with just the properties you need and give it a class to signal it's just a snippet of the resource (eg: 'summary', 'synopsis', etc), but still link to the full resource in the sub-entities 'self' link.

[Dmitry Pavlov]

Thank you for your answers!