O que é um recurso
Recurso é a entidade que uma API expõe e identifica. Um usuário, um pedido, um pet: cada um é um recurso que a API permite consultar e alterar. O recurso é o alvo das chamadas.
O recurso não é a mesma coisa que o dado interno. É a exposição da entidade pela API. A forma como o recurso é identificado e representado define como quem consome a API interage com o conteúdo.
Identificar o recurso
A URL identifica o recurso. O caminho mostra o tipo de recurso, e o identificador mostra o elemento específico. /pets representa o conjunto, e /pets/5 representa um elemento dentro dele.
O método HTTP comunica a operação sobre o recurso. Consultar, criar, substituir ou remover usam verbos diferentes. O recurso é o mesmo, e a ação é definida pelo método da chamada.
GET /pets → consultar a lista
POST /pets → criar um pet
GET /pets/5 → consultar o pet 5
DELETE /pets/5 → solicitar a remoçãoRepresentação do recurso
A resposta entrega o recurso em uma representação. O formato mais comum é o JSON, que estrutura o conteúdo em campos e valores. A representação descreve o estado do recurso no momento da chamada.
O formato da representação é parte do contrato da API. Quem consome precisa entender a estrutura para usar o conteúdo. A documentação informa os campos e o formato esperado em cada operação.
Recurso e sub-recurso
Um recurso pode conter ou se relacionar com outros. O sub-recurso aparece dentro de um contexto no caminho. A relação entre recursos ajuda a organizar a API conforme o domínio.
Modelar os recursos acompanha a realidade do negócio. Um usuário com pedidos, uma loja com produtos: cada relação vira um caminho que comunica o contexto. O recurso é a base dessa organização.
Para modelar os recursos da sua API e a relação entre eles, o Desenvolvimento Colaborativo da Dev Side Studio oferece orientação na organização das chamadas.
Dúvidas frequentes
Perguntas frequentes sobre Recurso
- Recurso e entidade são a mesma coisa?
- São próximos. A entidade descreve o que existe no domínio. O recurso é a exposição dessa entidade pela API. A mesma entidade pode ser exposta como um ou mais recursos.
- Como identificar um recurso específico?
- Pelo caminho e, quando necessário, pelo identificador. O recurso geral está em `/pets`, e um elemento específico em `/pets/5`. O identificador seleciona o recurso.
- O que é a representação do recurso?
- É o formato em que o recurso é entregue na resposta, como JSON. A representação descreve o estado do recurso, e o formato define como o conteúdo é estruturado.
- A mesma URL pode representar recursos diferentes?
- O caminho identifica o recurso, e o método comunica a ação. Uma URL com métodos diferentes pode executar operações diferentes, mas o recurso alvo é o mesmo.
Para continuar
Recursos relacionados
Documentação
REST: recursos na MDN
Como recursos são identificados e operados em uma API REST.
Abrir recursoDocumentação
Modelagem de recursos
Como desenhar recursos e relações em uma API.
Abrir recursoAplicação na formação
Developer Workspace
O recurso é a entidade que a API expõe e que as chamadas consultam e alteram.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.