I have a NoSQL repository with two tables, Foo and Bar. Each Foo has some metadata and a list of Bar ids. Each Bar has some metadata.

I'm writing the API for retrieving a Foo and would like to provide the ability to specify whether the returned Foo contains either the related Bar ids or the related Bar objects.

For example, one could GET /foo/foo-id-1?resolve=false and receive the response

  "id": "foo-id-1",
  "metadata": {...},
  "bars": ["bar-id-1", "bar-id-2", ...]

Versus GET /foo/foo-id-1?resolve=true and receiving

  "id": "foo-id-1",
  "metadata": {...},
  "bars": [
      "metadata": {}
      "metadata": {}
    }, ...

I'd like to do this because

  1. In the case that the client only needs the Foo metadata and not the Bar metadata, I can save a call to the repository to retrieve the Bar metadata.
  2. In the case that the client needs the Bar metadata included with the Foo, I can save the client a call by resolving the Bar ids to objects.

My questions are

  1. What should be the name of the parameter that provides this ability? I've named it "resolve" but is there something better (perhaps "projection") or a standard?
  2. Should the parameter be a flag, as I've suggested in the example above, or a string in case later more Foo children are added? For example, /foo/foo-id-1?resolve=bars,bazs.
  3. Is it ok to have an endpoint (GET on /foo:id) that returns two different data schemas? That is, in the first case the data schema contains bars :: [String] and in the second bars :: [Bar]
  • 1
    Your first question is likely to cause the whole post to be closed as "primarily opinion based". There is no general consensus to call such a parameter and your choice is as good as any other's. Oct 15, 2017 at 13:42
  • 1
    GraphQL was invented to solve this kind of problems in an uniform way. Just saying.
    – 9000
    Oct 15, 2017 at 15:51

1 Answer 1

  1. We typically call filling a "void" object with data "hydration". In that line of thought, you might want to have your parameter be "hydrate=1" or "hydrateRelated=foo,bar".

  2. A flag is simpler, but more limited. A string puts complexity on both sides of the API, but offers more flexibility. This is an engineering tradeoff, and you will have to decide for yourself which one makes sense in your case. There is no right answer for this type of problem in general.

  3. You can have "dehydrated" objects instead of strings, and then the schema is logically the same (but clients must be able to handle dehydrated objects, which from your question seems to be something that is needed anyway):

    { "id": "foo-id-1", "metadata": {...}, "bars": [ { "id": "bar-id-1" }, { "id": "bar-id-2" }, ... ] }

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.