O que é Sub-recurso?

O que é um sub-recurso

Sub-recurso é um recurso que existe dentro do contexto de outro. Em vez de aparecer no topo do caminho, ele é identificado em relação ao recurso pai. A relação fica visível na própria URL.

Um exemplo comum é o pedido dentro do usuário: /users/5/orders. O sub-recurso pertence ao contexto do usuário. A chamada age sobre o sub-recurso dentro desse contexto.

O caminho aninhado

O caminho aninhado expressa a relação. O recurso pai vem primeiro, e o sub-recurso vem depois. Os identificadores definem o elemento específico dentro de cada nível.

O caminho pode se aprofundar conforme a relação. Um sub-recurso pode ter seus próprios sub-recursos. Cada nível adiciona contexto à chamada, e a URL comunica a hierarquia.

GET /users/5/orders      → pedidos do usuário 5
GET /users/5/orders/2    → o pedido 2 do usuário 5
POST /users/5/orders/2/upload → upload no pedido 2

Quando usar sub-recurso

O sub-recurso faz sentido quando a relação é forte. O elemento só existe dentro do contexto do pai. A organização do caminho comunica essa dependência e ajuda quem consome a API a entender a relação.

A escolha, porém, acompanha o desenho. Um recurso pode aparecer no topo do caminho quando a relação não precisa ser forçada. O uso do sub-recurso é uma decisão de modelagem.

Sub-recurso e autorização

O contexto no caminho também participa da autorização. O sub-recurso existe dentro do recurso pai, e o acesso precisa confirmar a relação. A troca de um identificador no caminho não deve expor um elemento indevido.

A verificação confirma se o sub-recurso pertence ao contexto informado. O ID do pai e o ID do elemento definem o alvo, e a permissão controla o acesso. A combinação de caminho e autorização protege a chamada.

Para modelar os sub-recursos da sua API e a relação entre eles, o Desenvolvimento Colaborativo da Dev Side Studio oferece orientação na organização dos caminhos.

Aplicação na formação

Developer Workspace

O sub-recurso aparece no caminho dentro do contexto de outro recurso.

Conhecer a formação →