{"id":670,"date":"2015-12-08T13:16:14","date_gmt":"2015-12-08T16:16:14","guid":{"rendered":"https:\/\/www.semeru.com.br\/blog\/?p=670"},"modified":"2022-12-21T10:04:10","modified_gmt":"2022-12-21T13:04:10","slug":"restful-web-services","status":"publish","type":"post","link":"https:\/\/www.semeru.com.br\/blog\/restful-web-services\/","title":{"rendered":"RESTful Web Services"},"content":{"rendered":"

Dando seq\u00fc\u00eancia a s\u00e9rie de postagens sobre Web-services neste post, discutiremos sobre a JAX-RS 2.0 a especifica\u00e7\u00e3o para servi\u00e7os baseados em RESTful<\/strong>. No mundo REST<\/strong>, voc\u00ea pode acessar tudo como um recurso e eles possuem um identificador \u00fanico a URI(Uniform Resource Identifier)<\/strong>. Um servidor REST<\/strong> e seus clientes interagem usando o protocolo HTTP<\/strong> e seus quatro verbos mais conhecidos que s\u00e3o:<\/p>\n

POST – CREATE\/para inserir recurso<\/strong><\/p>\n

O verbo HTTP POST <\/strong>\u00e9 mais freq\u00fcentemente usado para criar novos recursos \u2014 inserir um novo item na base. Em uma aplica\u00e7\u00e3o REST <\/strong>perfeita quando uma opera\u00e7\u00e3o \u00e9 executada com sucesso, retorna-se o idempotente<\/a><\/strong> portanto seu uso n\u00e3o \u00e9 recomendado quando se precisa desse tipo de comportamento em uma requisi\u00e7\u00e3o. Fazendo duas requisi\u00e7\u00f5es POST<\/strong> id\u00eanticas o resultado mais comum ser\u00e1 duas respostas iguais com a mesma informa\u00e7\u00e3o mas ocasionalmente essa resposta pode mudar.<\/p>\n

GET – READ\/para selecionar\/recuperar um recurso<\/strong><\/p>\n

O verbo HTTP GET \u00e9 usado para ler ou recuperar uma representa\u00e7\u00e3o de um recurso. Em um “cen\u00e1rio feliz”, uma requisi\u00e7\u00e3o GET retorna uma representa\u00e7\u00e3o em XML <\/strong>ou JSON <\/strong>e um HTTP<\/strong> status code<\/a><\/strong> 200 (OK). Em um cen\u00e1rio de erro o retorno mais comum \u00e9 404 (NOT FOUND)<\/strong> ou 400 (BAD REQUEST)<\/strong>.
\nDe acordo com o design da especifica\u00e7\u00e3o HTTP<\/strong>, o verbo GET <\/strong>(juntamente com o HEAD<\/strong>) \u00e9 usado apenas para ler informa\u00e7\u00f5es e n\u00e3o para alter\u00e1-la. Portanto quando usado dessa maneira \u00e9 considerado seguro. Ou seja, ou seja eles podem ser invocados sem risco de perda ou corrup\u00e7\u00e3o de dados \u2014 chamando uma vez tem o mesmo efeito de cham\u00e1-lo 10 vezes, ou nenhuma. Al\u00e9m disso, o verbo GET <\/strong>(e HEAD<\/strong>) \u00e9 idempotente, o que significa que se fizermos m\u00faltiplas requisi\u00e7\u00f5es teremos sempre o mesmo resultado.
\nVoc\u00ea nunca deveria expor opera\u00e7\u00f5es inseguras via GET <\/strong>\u2014 ele nunca deve ser usado para modificar informa\u00e7\u00f5es no servidor.<\/p>\n

PUT – UPDATE\/para modificar um recurso<\/strong><\/p>\n

O verbo PUT <\/strong>\u00e9 comumente usado para atualizar informa\u00e7\u00f5es, colocando um recurso conhecido no (body) corpo da requisi\u00e7\u00e3o contendo novas informa\u00e7\u00f5es que representam o recurso original.
\nEntretanto, o verbo PUT <\/strong>tamb\u00e9m pode ser usado para criar um recurso caso o ID <\/strong>do mesmo seja definido pelo cliente ao inv\u00e9s do servidor. Em outras palavras se o verbo PUT \u00e9 proveniente de uma URI <\/strong>que n\u00e3o contenha um recurso com um ID preexistente. Nesse caso o corpo da requisi\u00e7\u00e3o cont\u00e9m a representa\u00e7\u00e3o de um recurso. Para muitos isso pode parecer complicado e confuso. Conseq\u00fcentemente, este verbo deve ser usado com modera\u00e7\u00e3o para a cria\u00e7\u00e3o de um novo recurso.
\nUma alternativa para isso \u00e9 utilizar o verbo POST<\/strong> para criar novos recursos com o ID definido pelo cliente setado no corpo da requisi\u00e7\u00e3o \u2014 caso n\u00e3o tenha o ID <\/strong>definido para o recurso deve-se usar o verbo POST<\/strong>(confira acima).
\nUm update bem sucedido, retorna um status code<\/strong> 200 (ou 204 quando n\u00e3o retorna nenhum conte\u00fado no body. Se estiver usando o verbo PUT<\/strong> para criar um novo recurso, o retorno deve ser um status code<\/strong> 201 em caso de uma cria\u00e7\u00e3o bem sucedida. O response body \u00e9 opcional \u2014 lembrando que quando ele \u00e9 exposto h\u00e1 um consumo maior de banda. Caso o cliente seja o respons\u00e1vel por definir o ID <\/strong>do recurso n\u00e3o \u00e9 necess\u00e1rio retornar um link para o mesmo via location header.
\nO verbo PUT <\/strong>n\u00e3o \u00e9 uma opera\u00e7\u00e3o segura, na medida em que modifica(ou cria) um recurso no servidor, mas ele \u00e9 idempotente. Em outras palavras, se voc\u00ea cria ou atualiza um recurso usando o verbo PUT <\/strong>e executa a mesma opera\u00e7\u00e3o de novo, o recurso ter\u00e1 o mesmo estado que na primeira execu\u00e7\u00e3o.
\nSe, por exemplo, voc\u00ea fizer uma requisi\u00e7\u00e3o PUT <\/strong>para um recurso que incrementa um contador dentro de um recurso, a requisi\u00e7\u00e3o perde o comportamento de idempotente. As vezes isso acontece sendo suficiente apenas documentar a requisi\u00e7\u00e3o como n\u00e3o idempotente. Entretanto, o recomendado para requisi\u00e7\u00f5es PUT <\/strong>\u00e9 implementar apenas requisi\u00e7\u00f5es idempotentes. Sendo assim \u00e9 fortemente recomendado o uso do verbo POST <\/strong>para opera\u00e7\u00f5es n\u00e3o idempotentes.<\/p>\n

DELETE – DELETE\/para remover um recurso<\/strong><\/p>\n

O verbo DELETE \u00e9 f\u00e1cil de entender, ele \u00e9 usado para deletar um recurso identificado por uma URI.
\nEm uma dele\u00e7\u00e3o bem sucedida retorna-se um status code<\/strong> 200 (OK)<\/strong> juntamente com um response body, possivelmente uma representa\u00e7\u00e3o do item deletado (o que acaba por demandar muita banda), ou uma response customizada. Ou retornar o status code<\/strong> 204 (NO CONTENT)<\/strong> sem response body. Em outras palavras, um status code<\/strong> 204 sem corpo, ou JSEND-style response<\/a><\/strong> com um status code<\/strong> 200 s\u00e3o as responses mais recomendadas.
\nAs opera\u00e7\u00f5es de DELETE <\/strong>s\u00e3o idempotentes. Se voc\u00ea deleta um recurso, ele \u00e9 removido sendo imposs\u00edvel repetir a opera\u00e7\u00e3o uma vez que o recurso n\u00e3o existe mais. Se voc\u00ea utilizar o verbo DELETE <\/strong>para decrementar um contador (dentro de um recurso), sua opera\u00e7\u00e3o DELETE <\/strong>n\u00e3o ser\u00e1 mais idempotente. Como dito anteriormente, estat\u00edsticas de uso e m\u00e9tricas podem ser atualizadas enquanto o servi\u00e7o \u00e9 considerado idempotente e as informa\u00e7\u00f5es do recursos permanecem inalteradas. \u00c9 recomendado o uso do verbo POST para opera\u00e7\u00f5es n\u00e3o idempotentes.
\nExiste uma recomenda\u00e7\u00e3o quanto a idempot\u00eancia do DELETE entretanto repetir uma requisi\u00e7\u00e3o de DELETE<\/strong> em um recurso, normalmente, retorna um status code<\/strong> 404 (NOT FOUND) uma vez que j\u00e1 foi removido e, portanto, n\u00e3o existe mais. Para muitos uma opera\u00e7\u00e3o de DELETE <\/strong>n\u00e3o \u00e9 idempotente, entretanto, o resultado final do recurso \u00e9 o mesmo. Retornar um status code<\/strong> 404 \u00e9 aceit\u00e1vel e comunica com precis\u00e3o o status da requisi\u00e7\u00e3o.<\/p>\n

Como podemos perceber, esses quatro verbos nos permite tra\u00e7ar uma certa analogia entre os verbos HTTP <\/strong>e o SQL<\/strong>. Observando a tabela abaixo isto fica um pouco mais claro.<\/p>\n

\"image2\"<\/a><\/p>\n

Al\u00e9m dos verbos mencionados anteriormente temos outros menos usados.<\/p>\n

HEAD <\/strong>– O verbo HEAD<\/strong> possui uma funcionalidade similar ao verbo GET<\/strong>, exceto pelo fato do servidor retornar uma response line e headers, mas sem um entity-body.
\nTRACE <\/strong>– O verbo TRACE<\/strong> \u00e9 usado para recuperar o conte\u00fado de uma requisi\u00e7\u00e3o HTTP <\/strong>de volta podendo ser usado com o prop\u00f3sito de debug durante o processo de desenvolvimento.
\nOPTIONS <\/strong>– O verbo OPTIONS <\/strong>\u00e9 usado pelo cliente para encontrar opera\u00e7\u00f5es HTTP <\/strong>e outras op\u00e7\u00f5es suportadas pelo servidor. O cliente pode especificar uma URL <\/strong>para o verbo OPTIONS<\/strong> ou um asterisco (*) para se referir a todo o servidor.
\nCONNECT <\/strong>– O verbo CONNECT <\/strong>\u00e9 usado pelo cliente para estabelecer uma conex\u00e3o de rede com um servidor via HTTP<\/strong>.
\nPATCH<\/strong> – O verbo PATCH<\/a><\/strong> pode ser usado para realizar updates parcias de um recurso. Por exemplo, quando voc\u00ea precisar alterar apenas um campo em um recurso, executar um POST com todo o objeto \u00e9 pesado e acarreta em um maior consumo de banda. Levando isso em conta a primeira coisa que vem em mente \u00e9: “por que n\u00e3o usar o PATCH ao inv\u00e9s do PUT para realisar atualiza\u00e7\u00f5es sempre?”. Simples o verbo PATCH pode ser um problema na medida em que n\u00e3o \u00e9 idempotente. Al\u00e9m disso minimizar seu uso previne curup\u00e7\u00e3o de dados por “colis\u00f5es” entre duas PATCH requests no mesmo recurso em um mesmo frame de tempo. Colis\u00f5es entre multiplas PATCH requests s\u00e3o mais perigosas que colis\u00f5s entre PUT requests por que exige que o cliente tenha informa\u00e7\u00f5es b\u00e1sicas do recurso ou ir\u00e3o corromp\u00ea-lo.<\/p>\n

Formatos Suportados em Web Services RESTful<\/strong><\/p>\n