O primeiro conceito a se entender do REST é o **rescurso**. Ele é qualquer coisa a ser transferida na web. [![][1]][1] 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][2]: GET api.biblioteca.com/livros?autor=Homero [ { ... }, { ...} ] 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. PUT 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.][3] É 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. ## 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 [![][4]][4] 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.][5] [1]: https://i.sstatic.net/3vacv.jpg [2]: https://en.wikipedia.org/wiki/Query_string [3]: https://stackoverflow.com/questions/630453/put-vs-post-in-rest [4]: https://i.sstatic.net/F7yy1.png [5]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication