Se o projeto tem atividades, eis a forma correta de representar, diferenciando o PUT
de PATCH
. Como entendo que haverá o recurso /projetos/
e apenas o /atividades/
para o GET, vou organizar os possíveis endpoints pelos métodos HTTP.
GET
- Buscar todos os projetos:
GET /projetos/
- Buscar o projeto de número 1:
GET /projetos/1
- Buscar todas as atividades do projeto 1:
GET /projetos/1/atividades
- Buscar a atividade 1 do projeto 1:
GET /projetos/1/atividades/1
, mas uma opção também é apenas criar um /atividades/1
.
- Buscar a atividade 1:
GET /atividades/1
- Buscar todas as atividades:
GET /atividades/
POST
- Criar o projeto de número 1:
POST /projetos/
, passando no body da request as informações do projeto
- Criar uma atividade no projeto de número 1:
POST /projetos/1/atividades
, passando no body da request as informações da atividade
Você também poderia ter um POST /atividades/1
, passando o número do projeto no body. Esta decisão vai depender de como quer representar os recursos disponíveis. Esta "quebra" pode ser feita quando o seu endpoint começa a ficar muito extenso ou acredita que ele ficará melhor organizado. Se for optar pela quebra, o ideal é manter a coerência e também fazer a mesma quebra nos outros métodos HTTP do recurso.
PUT
Utilizado para substituir um recurso inteiro existente por outro.
- Substituir todo o conteúdo do projeto de número 1:
PUT /projetos/1
, passando no body da request todas as novas informações do projeto
- Substituir toda uma atividade de número 1 no projeto de número 1:
PUT /projetos/1/atividades/1
, passando no body da request as novas informações da atividade
PATCH
Utilizado para alterar apenas uma ou algumas informações específicas do recurso.
- Atualizar qualquer informação do projeto de número 1:
PATCH /projetos/1
, passando no body da request apenas as informações do projeto que gostaria de atualizar
- Atualizar qualquer informação de uma atividade de número 1 no projeto de número 1:
PATCH /projetos/1/atividades/1
, passando no body da request apenas as informações da atividade
DELETE
- Remover o projeto de número 1:
DELETE /projetos/1
- Remover uma atividade de número 1 no projeto de número 1:
DELETE /projetos/1/atividades/1
.
O DELETE
também pode ser usado quando o sentido é uma exclusão lógica do recurso, pois às vezes o pessoal só associa este método ao DELETE
do banco de dados, o que não faz sentido.
Lembre-se também de retornar códigos HTTP que sejam coerentes. Exemplo: 201 para criação de um recurso via POST
, 200 ou 204 no PUT
e DELETE
, 404 para quando não encontrar o recurso, etc.