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

Related Posts:

Qual a diferença entre AppCompatActivity e Activity? – android android-activity
Pergunta: Qual a diferença da AppCompatActivity para Activity ? A partir de qual versão a AppCompatActivity foi adicionada ao Android? Autor da pergunta Luhhh A diferença reside ...
Como abreviar palavras em PHP? – php string
Pergunta: Possuo informações comuns como nome de pessoas e endereços, e preciso que elas contenham no máximo 30 caracteres sem cortar palavras. Exemplo: 'Avenida Natalino João Brescansin' ...
Qual é a finalidade de um parêntese vazio numa declaração Lambda? – c# expressões-lambda característica-linguagem
Pergunta: Criei um exemplo de uma declaração Lambda sem argumentos, entretanto, estou com duvidas referente a omissão do parêntese vazio () na declaração. Veja o exemplo: class ...
Dúvidas sobre a integração do MySQL com Java – java mysql netbeans
Pergunta: Estou criando um sistema no NetBeans, utilizando a linguagem Java e o banco de dados MySQL. Escrevi o seguinte código para realizar a conexão ...
Qual é a finalidade da pasta Model do framework Inphinit? – php inphinit
Pergunta: No Inphinit micro-framework existe a pasta Model que fica dentro da pasta application, e nela é onde ficam as classes, mas eu estou muito ...
Uso do ‘@’ em variáveis – javascript typescript coffeescript
Pergunta: Vejo em algumas linguagens que compilam para javascript, como TypeScript e CoffeeScript, o uso do @ em variáveis, como também, casos em que o ...
Qual tamanho máximo um arquivo JSON pode ter? – json arquivo
Pergunta: Vou dar um exemplo para conseguir explicar minha duvida: Preciso recuperar informação de imagens vindas de uma API, esse banco de imagens me retorna JSON's ...
O que é Teste de Regressão? – terminologia engenharia-de-software testes
Pergunta: Na matéria de Teste de Software o professor abordou um termo chamado Teste de Regressão, isto dentro da disciplina de teste de software. Sendo ...
O que é um construtor da linguagem? – php característica-linguagem
Pergunta: Em PHP, já li e ouvi várias vezes a respeito dos Construtores da Linguagem. Os casos que sempre ouvi falar deles foi em casos ...
Função intrínseca para converter numérico para string – cobol
Pergunta: Estou a tentar saber se existe alguma função intrínseca do COBOL para converter um data numérico para string sem precisar usar a cláusula REDEFINES: ( ...
Porque usar implements? – java android
Pergunta: Qual a diferença entre usar btn.setOnClickListener(new OnClickListener() { e public class MainActivity extends Activity implements OnClickListener{ Estive fazendo um curso de Android e meu professor falou que ...
O que é XHTML e quando deve ser usado? – html xml xhtml
Pergunta: O que eu sei é que o XHTML precisa ser XML válido. Isso implica, por exemplo, que todas as tags precisam ser fechadas. Por ...
Uma placa aceleradora de vídeo pode melhorar o desempenho não-gráfico? [fechada] – desempenho
Pergunta: Para desenvolver em Ruby on Rails, eu utilizo aqui uma máquina virtual do VirtualBox com Ubuntu Server 14.04 sem interface gráfica instalada. Recentemente descobri uma ...
Concat() VS Union() – c# .net
Pergunta: Qual a diferença entre Concat() e Union() ? Quando usar Concat() e quando usar Union() ? Somente pode ser usado em list ? ...
Como usar randômico no C++? – c++
Pergunta: Gostaria de um exemplo da utilização do randômico no C++, pois preciso utiliza-lo mas não sei como funciona. Autor da ...

Deixe uma resposta

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