9

Já vi a documentação do W3C algumas perguntas aqui no SOpt:

Porém achei muito conceitual, ainda tenho algumas dúvidas de uso na prática, por exemplo, se eu tenho um sistema simples de usuários, eu possuo basicamente 5 operações: inserção (POST), busca (GET), alteração (PUT), exclusão (DELETE) e autenticação (a autenticação verifica os dados de um usuário e a busca pega os dados de todos usuário, sem necessitar dos seus dados de acesso). Se eu estiver errado me corrijam por favor

  1. Qual método eu vou usar para autenticação?
  2. Considerando que tenho 5 ações e que, de acordo com as respostas das perguntas mencionadas, existem 9 métodos "oficiais", quando eu vou utilizar os demais?
  3. Se eu utilizar o método GET para pegar algo muito importante, e, por isso, os dados do usuário devem ser novamente informados (usuário e senha), devo passar isso pela url (examplo.com/dado/usuario/senha)?
2
  • Resposta rápida: conceitualmente a autenticação não faz parte do recurso de usuários. Seria melhor você separar as responsabilidades e criar um serviço próprio, assim podendo utilizar todos os métodos que for necessário para a autenticação.
    – Woss
    Commented 20/05/2018 às 0:03
  • @AndersonCarlosWoss não entendi essa resposta rápida, pode explicar melhor?
    – Costamilam
    Commented 20/05/2018 às 0:42

5 Respostas 5

7
+50

Com o grande aumento do uso do protocolo HTTP em API esses métodos vieram mais a tona. Em transações diretas você pode usar o método que você quiser, porém alguns tem suas restrições, como o GET e o DELETE, por exemplo, não pode ter um corpo na requisição. Porém algumas linguagens essas restrições podem serem feridas. A importância dos diferentes métodos é um protocolo de compreensão do objetivo da requisição. E isso irá ajudar na compreensão dos recursos da sua aplicação. Vamos aos métodos do protocolo:

Métodos padrões do protocolo HTTP

  • GET: Método de requisição de informação. Esse método é útil para buscar alguma informação requisitada tanto pelo caminho http://meusite/api/usuarios ou http://meusite/api/usuarios/235 por um filtro http://meusite/api/usuarios?status=ativo. Como o objetivo é retornar alguma informação, então esse método não deve esperar um corpo na requisição. Assim o método terá uma transação mais rápida na requisição.
  • POST: Método de inserção de informação. É um método de extrema utilidade, pois é um método que irá executar uma ação. O método não é obrigatório um corpo nem na requisição e nem na resposta. Deve entender esse método como terá uma execução no servidor. Exemplos:

    1 - Inserir valores: Executando um POST em http://meusite/api/usuarios sendo no corpo os valores do novo usuário. Dessa forma sabemos que será inserido a informação do corpo na listagem de usuários.

    2 - Atualizar valores: Por mais que temos o método PUT, não é considerado quebra de protocolo usar o POST para fazer uma atualização de dados. Sendo por isso que os browser não utilizam o método PUT, pois no início do protocolo HTTP só existia os métodos GET e POST.

    3 - Executar alguma funcionalidade: Caso haja alguma execução de cálculo ou de funcionalidade mais especifica (não sendo uma consulta, pois isso é o GET) utiliza o protocolo POST para essa execução. Um exemplo seria http://meusite/api/usuarios/parabenizar-aniversariantes. Isso não quer dizer que essa funcionalidade haja um corpo tanto na requisição quanto na resposta.

  • PUT: É um método específico para atualizar valores. Não seria correto utilizar o PUT para execução de funcionalidade, como vimos no POST. Então terá como padrão um corpo na requisição e o caminho terá, por segurança, a chave referência que dos dados que estão sendo atualizado http://meusite/api/usuarios/234. Dessa forma o protocolo recusará as requisições que vierem sem uma chave.

  • PATCH: Um método de auxílio do PUT é o PATCH. Também tem como objetivo atualizar valores de uma referência chaveada no caminho http://meusite/api/usuarios/234, porém o corpo não terá o objeto completo. Sendo assim a atualização dos valores são parciais. Um exemplo é no processo de atualizar senha, não precisa mandar o corpo todo para a mudança de senha. Assim terá uma segurança e uma validação melhor em caso de mudança de senha e evita de incluir if no PUT.

    • Um exemplo em comparação entre o PUT e o PATCH teremos um objeto Usuário em que terá a seguinte corpo completo:

      {
      "Id":"7e8f2ae6-a5b1-41e7-b9fd-2ae8863fa39d",
      "Nome":"Joãozinho",
      "Email":"[email protected]",
      "Login":"joaozinho",
      "DataNascimento":"01/01/1990"
      }
      

      Para executar uma mudança de dado completa você utilizaria o PUT. Sendo assim a requisição seria (Não considerarei nenhum protocolo de Authorization):

    Método: PUT

    Url: http://meusite/api/usuarios/7e8f2ae6-a5b1-41e7-b9fd-2ae8863fa39d

    Heard: ["Content-Type":"application/json"]

    Body:

    {
        "Id":"7e8f2ae6-a5b1-41e7-b9fd-2ae8863fa39d",
        "Nome":"Joãozinho Sauro",
        "Email":"[email protected]",
        "Login":"joaozinho",
        "DataNascimento":"01/01/1990"
    }
    

    Já o PATCH seria uma compreensão que o processo utilizado nesse método é para uma alteração específica. Como exemplo farei um processo de alteração de login, pois iremos compreender que no lado do servidor ele terá um validador de login disponível, por exemplo. Então a requisição ficaria da seguinte forma:

    Método: PATCH

    Url: http://meusite/api/usuarios/7e8f2ae6-a5b1-41e7-b9fd-2ae8863fa39d/mudar-login

    Heard: ["Content-Type":"application/json"]

    Body:

    {
        "Login":"joaozinho30"
    }
    

    Como já disse, o protocolo não exija que você tenha que fazer dessa forma. Ele é útil para compreensões melhores de cada funcionalidade que seu serviço está oferecendo. Mas caso queira fazer esses dois exemplos no POST você pode. Onde a diferença de incluir um novo Usuário e atualizar os dados do Usuário estará na URL. Então isso fará parte da decisão arquitetural do projeto em qual padrão a equipe irá seguir. Mas caso o seu projeto será de uso público, será muito bem aceito se o serviço respeitar fielmente o protocolo.

  • DELETE: Apesar de ser um método novo para os primórdios do HTTP, mas, como o GET, é um método que não se deve passar um corpo. Dessa forma o processo ganha uma velocidade maior na requisição, já que o objetivo é simplesmente uma limpeza. Dessa forma o seu processo terá uma organização melhor, pois saberá que as exclusões estarão somente no método DELETE.

  • OPTIONS: Um método de uso maior dos browser. Quando utiliza o protocolo HTTPS por padrão os browser irão requisitar quais os métodos ele poderá utilizar com a url do momento. Dessa forma o processo irá retornar somente a lista de métodos permitidos executar, por exemplo POST, GET, PUT, DELETE.

  • HEAD: Não bastando a melhoria do tempo de transação do POST para o GET, o método HEAD terá um ganho a mais. Pois o objetivo é a informação que contenha no HEAD da resposta. Isso é muito útil para atualização de Token, por exemplo.

  • CONNECT: É um recurso do protocolo HTTP para que abra um túnel de conexão direta. Isso é útil para caso de processo de extrema segurança que irá abrir um espécie de VNP para comunicação.

  • TRACE: Um processo simples para testar a comunicação. Ele é útil para caso de uma execução muito demorada sendo processada por outros métodos e assincronamente o TRACE irá validade se ainda há comunicação com o servidor ou a demora é devido a uma queda de comunicação.

Guilherme, sendo assim você pode colocar a autenticação no método que você quiser, mas por padrão de protocolo e para facilitar a manutenção para os novos membros da equipe é melhor usar o método POST.

Bom, espero que eu atendi a sua expectativa. Mas foi de grande treino responder essa questão.

OBS: Já houve uma resposta para essa questão em outra postagem https://pt.stackoverflow.com/a/9421/114084, então complementei um pouco mais a minha compreensão para que possa compartilhar o meu entendimento.

6
  • O link que colocou está na pergunta e foi um dos que achei muito conceitual, gostei da resposta já que explica o que e mostra um exemplo prático, porém ainda estou com dúvida em relação ao PATCH poderia explicar um pouco mais? Como eu o uso e qual a diferença para o PUT?
    – Costamilam
    Commented 25/05/2018 às 2:00
  • fiz uma pergunta relacionada ao corpo das requisições, acredito que possa te interessar, ou a outros que estão pesquisando sobre o HTTP
    – Costamilam
    Commented 25/05/2018 às 2:03
  • Guilherme, eu fiz uma edição colocando um exemplo entre o PUT e o PATCH. Veja se ficou melhor. Commented 25/05/2018 às 13:12
  • Quanto a questão do corpo, no protocolo HTTP a requisição você pode fazer da forma que você quiser. Ninguém poderá te dizer que não poderá ter corpo, ou que a URL está errada, ou qualquer outra coisa. O que acontece que em algumas linguagens (Java ou .Net, por exemplo) não lhe entregará o corpo em caso de uso do método GET. Você poderá burlar isso, mas será um custo de programação muito cara ao invés de simplesmente aceitar o protocolo normal. É meio chatinho as exigências do protocolo, mas quando acostuma fica até mais fácil de trabalhar. rs Commented 25/05/2018 às 13:20
  • Entendi melhor, porém no exemplo surgiu uma última dúvida (espero), se eu quero que, quando um usuário for cadastrar ou alterar o campo username, fazer uma chamada pra api de acordo com o que ele digita para verificar se aquele usuário está disponível. Essa chamada é GET ou PATCH ou outro?
    – Costamilam
    Commented 25/05/2018 às 23:29
6

TL;DR: não é que precise existir um recurso para autenticação, porém precisa de autorização para que você manipule um recurso.


O primeiro conceito a se entender do REST é o recurso. Ele é qualquer coisa a ser transferida na web.

De forma metafórica, pense em uma biblioteca. Ela possui diversos recursos: livros, pessoas, funcionários.

GET

É muito simples pensar no REST dessa forma. Se quero saber sobre um livro, eu posso fazer:

GET api.biblioteca.com/livros/iliada

{
  "autor": "Homero",
  "título": "Ilíada",
  "descrição": "A Ilíada (em grego antigo: Ἰλιάς, IPA: [iːliás]) é um dos dois principais poemas épicos da Grécia Antiga, de autoria atribuída ao poeta Homero, que narra os acontecimentos decorridos no período de 50 dias durante o décimo e último ano da Guerra de Troia, conflito empreendido para a conquista de Ílion ou Troia, cuja gênese radica na ira (μῆνις, mênis) de Aquiles."
}

Se quero todos os livros de Homero, faço parecido, mas com uma query string:

GET api.biblioteca.com/livros?autor=Homero

[ { ... }, { ...} ]

Ou dependendo do design da sua API, poderia ser também: api.biblioteca.com/autor/homero/livros

Pode-se concluir que o método HTTP GET, em REST, é utilizando para retornar um ou mais recursos.

DELETE

Se você precisa tirar um livro da biblioteca, é só utilizar o DELETE.

DELETE api.biblioteca.com/livros/iliada

POST

Esse método envia dados para o servidor. No REST, utilizamos para criar um novo recurso.

Por não ser idempotente, não se pode cachear a resposta de uma requisição como esta.

POST api.biblioteca.com/livros

{
  "autor": "William Shakespeare",
  "título": "Macbeth",
  "descrição": "Macbeth é uma tragédia do dramaturgo inglês William Shakespeare, sobre um regicídio e suas consequências. É a tragédia shakespeariana mais curta, e acredita-se que tenha sido escrita entre 1603 e 1607. O primeiro relato de uma performance da peça é de abril de 1611, quando Simon Forman registrou tê-la visto no Globe Theatre, em Londres. A obra foi publicada pela primeira vez no Folio, de 1623, possivelmente a partir de uma transcrição de alguma performance específica."
}

PUT

Assim como o POST, é utilizado para enviar dados ao servidor. No REST, é utilizado para atualizar recursos únicos, como um livro em específico.

Por ser idempotente, a resposta das requisições podem ser cacheadas.

PUT api.biblioteca.com/livros/arte-da-guerra

{
  "autor": "Sun Tzu",
  "título": "Arte da Guerra"
}

PATCH

Assim como o PUT, é utilizado para enviar dados ao servidor. No REST, é utilizado para atualização de recursos parciais. Como por exemplo, adicionar ou atualizar um só campo em uma entidade.

Pode ou não ser idempotente, por isso pode ser um método um pouco confuso.

PATCH api.biblioteca.com/livros/arte-da-guerra

{
  "descrição": "A Arte da Guerra (chinês: 孫子兵法; pinyin: sūn zĭ bīng fǎ, literalmente "Estratégia Militar de Sun Tzu"), é um tratado militar escrito durante o século IV a.C. pelo estrategista conhecido como Sun Tzu. O tratado é composto por treze capítulos, cada qual abordando um aspecto da estratégia de guerra, de modo a compor um panorama de todos os eventos e estratégias que devem ser abordados em um combate racional. Acredita-se que o livro tenha sido usado por diversos estrategistas militares através da história como Napoleão, Zhuge Liang, Cao Cao, Takeda Shingen, Vo Nguyen Giap e Mao Tse Tung."
}

POST vs PUT vs PATCH

Existem inúmeras discussões comparando os dois métodos e seu uso. É importante ressaltar que o REST é somente um padrão, e que não resolve todos os casos.

  • Use POST para criação de novos recursos em endpoints de coleção, como api.biblioteca.com/livros.
  • Use PUT para atualização de recursos em endpoints de entidade, como api.biblioteca.com/livros/iliada.
  • Use PATCH para atualização parcial de recursos, também em endpoints de entidade.

Em resumo...

GET POST PUT PATCH DELETE
Requisição aceita body? Não Sim Sim Sim Sim
Resposta aceita body? Sim Sim Sim Sim Sim
Altera estado dos recursos? Não Sim Sim Sim Sim
É idempotente? Sim Não Sim Não Sim
É cacheável? Sim Não* Não Não Não

* depende do que vier nos headers

Ok, mas e a autenticação?

Como comentei, o REST não resolve tudo, e nem deve. Nem tudo são recursos ou podem ser representados como um. Aí vai de implementação para implementação.

Existem diversas formas de autenticar utilizando HTTP, e a grande maioria não tem nada a ver com método HTTP, e sim sessões, cookies ou cabeçalhos HTTP.

O ponto é: não é que precise existir um recurso para autenticação, porém precisa de autorização para que você delete um livro, por exemplo.

Autenticação básica com HTTP

A dica de ouro, primeiramente, é estar utilizando HTTPS. A cada requisição feita, um cabeçalho HTTP indicando um token de autenticação.

DELETE api.biblioteca.com/livros/arte-da-guerra 
Authorization: Basic QWxhZGRpxjpvcGVuIHNlc2FtZS==

Recomendo ler mais sobre esse método de autenticação na MDN.

2
  • 1
    Sua resposta virou referência para REST, vou por ela nas leituras obrigatórias daqui da empresa. Commented 18/06/2018 às 16:06
  • Fico feliz de ouvir isso, @JeffersonQuesado!
    – vinicius
    Commented 18/06/2018 às 16:15
3

Qual método eu vou usar para autenticação?

Para responder aquilo que comentei e não foi abordado nas outras respostas.

Recurso de usuário é diferente de recurso de autenticação. Imagine que você possua o recurso de usuário sob a URI /user, então:

  • GET /user busca informações de usuário;
  • POST /user cria um novo usuário;
  • PUT /user atualiza/cria dados do usuário;
  • DELETE /user exclui um usuário;
  • PATCH /user atualiza um usuário;

Como autentica um usuário? Com outro recurso, por exemplo, /auth.

  • GET /auth busca informações de uma autenticação;
  • POST /auth cria uma nova autenticação;
  • etc;

Se você deseja autenticar um usuário cadastrado, basta efetuar um POST para o recurso de autenticação. Normalmente esta requisição irá gerar um token que identifica qual é a autenticação do usuário e, normalmente, esse token é armazenado nos cookies do cliente.

Considerando que tenho 5 ações e que, de acordo com as respostas das perguntas mencionadas, existem 9 métodos "oficiais", quando eu vou utilizar os demais?

As outras respostas abordam esse assunto.

Se eu utilizar o método GET para pegar algo muito importante, e, por isso, os dados do usuário devem ser novamente informados (usuário e senha), devo passar isso pela URL (exemplo.com/dado/usuario/senha)?

Não, os dados do usuário para autenticação devem ser passados exclusivamente para o recurso de autenticação. Ter que passar isso a outro recurso seria redundância e prejudicaria a atomicidade dos seus recursos. Se outro recurso precisa de autenticação para acessá-lo, você deve passar apenas o token de autenticação, através dos cabeçalhos da requisição, e validá-lo no lado do servidor. A resposta do vnbrs exemplifica muito bem isso na parte que fala da autenticação.

2
  • Não é o caso, mas estaria semanticamente incorreto usar user|client|worker/auth, se por exemplo eu tenho autenticação de usuários, funcionários e clientes e cada uma tem uma forma diferente?
    – Costamilam
    Commented 31/05/2018 às 0:10
  • Não, perfeitamente aceitável. A URI é opaca, ela não reflete nenhuma lógica implementada no servidor, então apenas por possuir user no caminho não significa, necessariamente, que pertence ao recurso de usuários.
    – Woss
    Commented 31/05/2018 às 0:15
2

Olá,

Vou tentar ir direto ao ponto, respondendo apenas as suas perguntas.

Qual método eu vou usar para autenticação?

Geralmente usa-se o método POST. Com certeza a autenticação é um conceito que não parece ser encaixar muito bem em qualquer método HTTP, mas normalmente adota-se o POST nestes casos :)

Considerando que tenho 5 ações e que, de acordo com as respostas das perguntas mencionadas, existem 9 métodos "oficiais", quando eu vou utilizar os demais?

Infelizmente você não vai conseguir sempre achar um método HTTP adequado para todas as ações que deseja fazer no sistema. Inclusive, tome cuidado ao utilizar alguns dos métodos HTTP mais raros, pois você pode ter problemas inesperados com firewall entre outras surpresas de ambiente.

Normalmente o pessoal se prende aos mais clássicos: GET, POST, PUT, DELETE e (mais raro) PATCH. O PATCH é usado quando o usuário quer atualizar apenas informações específicas da entidade HTTP e não quer enviar todas as informações a cada atualização, como é feito no PUT.

Se eu utilizar o método GET para pegar algo muito importante, e, por isso, os dados do usuário devem ser novamente informados (usuário e senha), devo passar isso pela url (examplo.com/dado/usuario/senha)?

Passar o usuário e senha pela URL é algo que nunca deve ser feito. Se determinado endpoint de consulta precisa do usuário e senha, esta informação deve ser passada no corpo da mensagem (body). Como o GET não aceita um body (ou não deveria aceitar..), usa-se POST mesmo. Exemplo:

POST /api/consultar-dado-importante/123

Body: 
{
    "usuario": "user", "senha": "123456"
}

Usar POST ao invés de GET nestes casos é uma exceção a regra.

No mais, fica a minha dica: você não vai encontrar uma resposta pronta de como usar o método ou código HTTP correto para cada problema no seu projeto. Tente apenas escolher um padrão na sua API e seguir ele o tempo todo, criando um padrão interno.

Se tiver mais alguma dúvida ou algo que não ficou claro, use a área de comentários que posso esclarecer melhor alguns pontos.

-8

geralmente tem sim, sempre várias operações que você pode fazer nesse caso.

Mas as mais utilizadas é o GET e o POST conforme você ja deve ter lido, provável que já tenha ciência do que faz cada uma:

GET = Mais RAPIDO, porém MENOS SEGURO.

POST = Mais LENTO, porem MAIS SEGURO.

ou seja, use get para passar alguma informação que não seja relevante para o servidor atraves da url. e use o post para passar alguma informação como senha, ou numero de cartão de credito, algo que seja mais confidencial que voce nao pode deixar visivel pela url.

Acredito que você agora entenda melhor qual deve usar.

2
  • Sua resposta está um pouco vaga e responde apenas o que não foi perguntado (GET vs POST), acrescente mais dados, por exemplo, porque é mais ou menos rápido e seguro? (desculpe se pareço ingrato não é a intenção :) )
    – Costamilam
    Commented 19/05/2018 às 21:45
  • 3
    Eu também fiquei curioso com essas afirmações. Por quais motivos afirva que um é mais rápido que outro e porquê um é mais seguro? Ambos enviam a informação através de texto, então qual seria a diferença na segurança?
    – Woss
    Commented 19/05/2018 às 23:59

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .