Uma API REST pode retornar vários recursos como um único recurso composto?

Estou no processo de criação de uma API REST e, atualmente, estou encontrando o seguinte problema:

• Fooé o primeiro recurso. As operações CRUD podem ser aplicadas via /foo/URI.
• Baré o segundo recurso. As operações CRUD podem ser aplicadas via /bar/URI.
• Todos Fooestão associados a zero ou um Bar. A razão pela qual eu não trato Barcomo um sub-recurso de Fooé porque a mesma Barinstância pode ser compartilhada entre vários Foo. Por isso, achei melhor acessá-lo por meio de um URI independente em vez de /foo/[id]/bar.

Meu problema é que, em uma quantidade significativa de casos, os clientes que solicitam uma Fooinstância também estão interessados ​​na Barinstância associada . Atualmente, isso significa que eles precisam executar duas consultas em vez de uma. Quero apresentar uma maneira que permita obter os dois objetos com uma única consulta, mas não sei como modelar a API para fazer isso. O que eu vim até agora:

• Eu poderia introduzir um parâmetro de consulta semelhante a este: /foo/[id]?include_bar=true. O problema dessa abordagem é que a representação do recurso (por exemplo, a estrutura JSON) da resposta precisaria parecer diferente (por exemplo, um contêiner, como em { foo: ..., bar: ... }vez de apenas um serializado Foo), o que torna o Fooponto final do recurso "heterogêneo". Eu não acho isso bom. Ao consultar /foo, os clientes sempre devem obter a mesma representação de recurso (estrutura), independentemente dos parâmetros de consulta.
• Outra idéia é introduzir um novo ponto de extremidade somente leitura, por exemplo /fooandbar/[foo-id]. Nesse caso, não há problema em retornar uma representação como { foo: ..., bar: ... }, porque é apenas a representação "oficial" do fooandbarrecurso. No entanto, não sei se esse ponto de extremidade auxiliar é realmente RESTful (foi por isso que escrevi "can" no título da pergunta. É claro que é tecnicamente possível, mas não sei se é uma boa idéia).

O que você acha? há outras possibilidades?

Uma API REST de nível 3 retornará um Fooe também um link indicando o relacionado Bar.

GET /foo/123
<foo id="123">
  ..foo stuff..
  <link rel="bar" uri="/bar/456"/>
</foo>

Você pode adicionar um recurso "drill down" à sua API que permite a navegação de links;

GET /foo/123?drilldown=bar
<foo id="123">
  ..foo stuff..
  <link rel="bar" uri="/bar/456">
    <bar id="456">
      ..bar stuff...
    </bar>
  </link>
</foo>

O recurso de pesquisa detalhada fica na frente das APIs e intercepta as respostas. Ele faria as chamadas de busca detalhada e preenchia os detalhes antes de devolver a resposta ao chamador.

Isso é bastante comum no REST de nível 3, pois reduz bastante a conversação de cliente / servidor em http lento. A empresa em que trabalho produz uma API REST de nível 3 com exatamente esse recurso.

Atualização: quanto vale a pena, veja como ele pode parecer no JSON. É assim que nossa API a estruturaria. Observe que você pode aninhar suas pesquisas detalhadas para obter links de links etc.

GET /foo/123?drilldown=bar

{
  "self": {
    "type": "thing.foo",
    "uri": "/foo/123=?drilldown=bar",
    "href": "http://localhost/api/foo/123?drilldown=bar"
  },
  "links": [
    {
      "rel": "bar",
      "rev": "foo",
      "type": "thing.bar",
      "uri": "/bar/456",
      "href": "http://localhost/api/bar/456"
    }
  ],
  "_bar": [
    {
      "self": {
        "type": "thing.bar",
        "uri": "/bar/456",
        "href": "http://localhost/api/bar/456"
      },
      "links": [
        {
          ..other link..
        },
        {
          ..other link..
        }
      ]
    }
  ]
}

Se 95% de todas as consultas deseja Foo, bem como Bar, em seguida, simplesmente devolvê-lo dentro do Fooobjeto quando você solicitar um Foo. Basta adicionar uma propriedade bar(ou algum outro termo para o relacionamento) e colocar o Barobjeto lá. Se o relacionamento não existir, use null.

Eu acho que você está pensando demais nisso :)