Over a million developers have joined DZone.

Are Subqueries RESTful?

DZone's Guide to

Are Subqueries RESTful?

· Integration Zone
Free Resource

Share, secure, distribute, control, and monetize your APIs with the platform built with performance, time-to-value, and growth in mind. Free 90-day trial of 3Scale by Red Hat

Twitter is great for one-liners, but it's very difficult to carry on any kind of advanced conversation there. Therefore when I saw this tweet yesterday, I knew I'd be picking a different medium to reply:

The blog seems like a good place, as I can put examples and all kinds other things here, and waffle at length (which is really why I like it!). Because when condensed to tweet form, the answer is really "it depends".

The Problem(s)

REST is all about representations of resources. They might come in different formats, and they might appear at their own URI as well as in one or more collections, but essentially you just get a representation of a thing. This is great, apart from when it isn't.

  • What if you want a smaller result set with only a limited number of fields?
  • What if you want related data? For every resource in a collection?

There are a couple of tactics that I deploy each time I need to solve one of these problems, but they all revolve around remodelling the resource structure. Just as we sometimes move fields around for database design or normalisation, we can do exactly the same with a RESTful service to make the resulting output make more sense to consumers. I thought I'd share examples of these tactics in this post.

More Verbose, Less Verbose

If a resource can be delivered in multiple formats, say XML or JSON, then why not in multiple "verbosities"? Sometimes you only want the outline of a resource, for example if you're display news items, you might only want the title and posting date. When you come to display that specific resource though, you'll want all the details, so you might end up with data structures like this:

Standard record:

  • Title
  • Author
  • Date
  • Excerpt

Verbose record:

  • Title
  • Author
  • Date
  • Excerpt
  • Full Article
  • Collection of Related Articles

If you want an in-the-wild example, try the Joind.in API. All the records there come in a fairly minimal format, but you can request more fields by adding verbose=yes as a GET parameter. Compare the API response (it's HTML, you can just click) for the recent DPC conference http://api.joind.in/v2.1/events/1109 with its verbose version http://api.joind.in/v2.1/events/1109?verbose=yes.

Splitting into Subresources

The alternative to allowing different verbosity of representations is to remove part of the record as it might be stored in the database into a separate resource.

So if your article is stored at http://example.com/articles/42, this would show the abbreviated version of the record from the structure above. Then you could offer the main body of the article at a separate location, such as http://example.com/articles/42/body. This does lead to repeated queries but if you only need the extra detail when you want to display a single record, it may well be worth the tradeoff - of course your mileage will vary between different applications.

Nesting Likely Data

The final tactic I want to share is where the server has a good idea that information will be needed from more than one source. There's a good example in the wild from GitHub - if you grab a list of issues over their API, you'll get the full user object of the user that created each issue. This makes sense because we'll always want to display who created the issue.

As an example, try requesting this URL with curl or your favourite API tool: https://api.github.com/repos/zendframework/zf2/issues and have a look at the structure that's returned (and as a total aside, admire the pretty-printing! I love GitHub's API)

Generic Solutions

There certainly are generic solutions, where you can basically express the select statement in URL form, but I'm not a huge fan of this approach. I'm sure there will be links to excellent resources in the comments of this article (thanks, people!)

Explore the core elements of owning an API strategy and best practices for effective API programs. Download the API Owner's Manual, brought to you by 3Scale by Red Hat


Published at DZone with permission of Lorna Mitchell, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.


Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.


{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}