Yoga framework for REST-like partial resource access

A tweet by Stefan Tilkov brought Yoga to my attention, “a framework for supporting REST-like URI requests with field selectors”.

As the name suggests, “Yoga” lets you practice some contortions that would strain a run-of-the-mill REST programmer. Basically, you can use a request like

GET /teams/4234.json?selector=:(members:(id,name,birthday)

to retrieve the id, name and birthday of all members of a softball team, rather than having to retrieve the team roaster and then do a GET on each and every team member to retrieve their name and birthday (and lots of other information you don’t care about).

Where have I seen this before? That use case came up over and over again when we were using SOAP Web services for resource management. I have personally crafted support for it a few times. Using this blog to support my memory, here is the list of SOAP-related management efforts listed in the “post-mortem on the previous IT management revolution”:

WSMF, WS-Manageability, WSDM, OGSI, WSRF, WS-Management, WS-ResourceTransfer, WSRA, WS-ResourceCatalog, CMDBf

Each one of them supports this “partial access” use case: WS-Management has :

WSMF, WS-Manageability, WSDM, OGSI, WSRF, WS-Management, WS-ResourceTransfer, WSRA, WS-ResourceCatalog, CMDBf

Each one of them supports this “partial access” use case: WS-Management has SelectorSet, WSRF has ResourceProperties, CMDBf has ContentSelector, WSRA has Fragments, etc.

Years ago, I also created the XMLFrag SOAP header to attack a more general version of this problem. There may be something to salvage in all this for people willing to break REST orthodoxy (with the full knowledge of what they gain and what they loose).

I’m not being sarcastic when I ask “where have I seen this before”. The problem hasn’t gone away just because we failed to solve it in a pragmatic way with SOAP. If the industry is moving towards HTTP+JSON then we’ll need to solve it again on that ground and it’s no surprise if the solution looks similar.

I have a sense of what’s coming next. XPath-for-JSON-over-the-wire. See, getting individual properties is nice, but sometimes you want more. You want to select only the members of the team who are above 14 years old. Or you just want to count these members rather than retrieve specific information about them individually. Or you just want a list of all the cities they live in. Etc.

But even though we want this, I am not convinced (anymore) that we need it.

What I know we need is better support for graph queries. Kingsley Idehen once provided a good explanation of why that is and how SPARQL and XML query languages (or now JSON query languages) complement one another (wouldn’t that be a nice trifecta: RDF/OWL’s precise modeling, JSON’s friendly syntax and SPARQL’s graph support – but I digress).

Going back to partial resource access, the last feature is the biggie: a fine-grained mechanism to update resource properties. That one is extra-hard.


Filed under API, CMDBf, Everything, Graph query, IT Systems Mgmt, Manageability, Mgmt integration, Modeling, Protocols, Query, REST, SOAP, SOAP header, Specs, Standards, Web services, WS-Management, WS-ResourceCatalog, WS-ResourceTransfer, WS-Transfer, XMLFrag, XPath

5 Responses to Yoga framework for REST-like partial resource access

  1. I agree we don’t need a generic property querying mechanism like that; because it’s not something that needs to be visible throughout the web as a whole. Flexible query mechanisms driven by hypertext (a common example being html form GET queries) provide the necessary to solve this problem on a per-app basis. URI templates are another decent avenue if you’re not using html.

    What sorts of application and use-cases would arbitrary graph queries be a ‘killer feature’? I understand value for exposed linked open data sets, but for your every-day application where’s the value? I think I’d argue again that flexible but pre-established queries driven by hypertext would be more than adequate for the majority of use cases.

    Again, on the ‘find-grained-mechanism’ for updating resource properties.. just not convinced that sort of generic mechanism is actually necessary. If you have portions of a resource that really need to be separate for whatever reason; then give them their own URI where you can update them exclusively, and embed them back into the origin resource. If this sounds complicated then the media type you’re using isn’t good enough! Fwiw, I created (and recently drew up a rough spec) for a media type that helps to make this trivial by including a component specifically designed for embedding resources.

    Missed Stefan’s tweet so thanks for bringing this to my attention! :)


  2. Oh – if you’re interested the spec of the media type I’m referring to above, is here:

  3. Hi Mike,

    Thanks for the comment and the pointer. I don’t know if a generic property mechanism needs to be “visible throughout the web as a whole”. All I know is that it’s needed for IT management (sorry, I mean “Cloud”) scenarios. We need to solve it in that context. Whether the solution is specific to that domain or is more general, I don’t really have a strong opinion on that.

    The other thing that we need is a description document (see But at this pointI am not sure whether HAL is going after that or not. I first heard of it via Erik Wilde’s tweet stating that it is a RESTful description language, but he and I may not mean the same thing by that word. I am looking for metadata that tells me more (than a MIME type) about the content I can expect to find in a resource description.

  4. I don’t see those 2 concerns as vastly, if even at all, different to one another in practice. Isn’t that the point?! :)

    HAL’s not a description language but i guess you could use it that way if you wanted to. It’s an application language like HTML for machines. @type is actually optional the application control is @rel and is, I think, what you are after.


  5. Your points are well taken and they were certainly taken into account when I joined the project. I’m not going to take credit for the “selector” portion of the Yoga projects. However, I will take advantage of another aspect of the project that is hitherto undocumented.

    Selector must be implemented somewhere between the Controller and the View. That process hijacks the MVC pattern to implement something that looks more like “REST orthodoxy” (in the Roy Fielding sense) than existing MVC frameworks.

    The yoga-fire project (under demos) implements linking between resources based on a combination of JPA and JAX-RS metadata. There will be more Roy Fielding RESTiness coming soon.

    If you have a few minutes, please check out the updated documentation: