Boas práticas para URI em API RESTful – api rest restful

Pergunta:


Estou com dúvida em relação às URIs de alguns recursos da api que estou desenvolvendo. Tenho os recursos projetos e atividades com relação 1-N, ou seja, um projeto tem várias atividades e uma atividade pertence à um projeto.

Qual a forma correta ou a melhor forma em relação às convenções REST? Gostaria de alguns exemplos para requisições GET, POST, PUT e DELETE para estes recursos.

EDIT: Reformulei a pergunta.

Autor da pergunta Fernando Zabin

Dherik

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.

Poderia utilizar a seguinte abordagem:

get /projetos # Lista de projetos    
post /projetos # Criar um projeto

get /projetos/1 # Buscar o projeto com id 1
put /projetos/1 # Atualizar o projeto com id 1
delete /projetos/1 # Deletar o projeto com id 1

get /atividades # Todas as atividades
post /atividades # Criar nova atividade

get /atividades/1 # Atividade com id 1
put /atividades/1 # Atualizar atividade com id 1
delete /atividades/1 # Deletar atividade com id 1

get /projetos/1/atividades # Lista de atividades do projeto com id 1

Lembrando a RFC 5789, o método put seria para substituir um recurso. Use o patch para modificá-lo. https://stackoverflow.com/questions/24241893/rest-api-patch-or-put

Pode conferir nestas perguntas, sobre design das URI

https://stackoverflow.com/questions/13038943/restful-api-uri-design

https://stackoverflow.com/questions/7833548/hierarchical-restful-url-design

Fonte

Deixe uma resposta

O seu endereço de email não será publicado. Campos obrigatórios marcados com *