Right-Size Your RESTful API: More Flexibility Without GraphQL

If you publish a RESTful API and there are situations when you need less (or more!) detail in the API responses from your API – then this post is for you. When I run into this with the teams I advise, the initial problem statement usually arrives more like “We need to move to GraphQL”, but this is a solution, not a problem to solve. The problem usually turns out to be either or both of:

  • the API responses are simply too large for some of the clients or uses cases, users need to select just the fields they want
  • the API doesn’t have enough information in the response payload for this client or use case, users need to choose to include nested data

GraphQL is one way to achieve these things, but this post is about the RESTful way to provide the right level of detail in an API response. Continue reading

Are Subqueries RESTful?

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?

Continue reading