Restful API

Sumário

Restful é um padrão de arquitetura de software para criar e disponibilizar serviços na web, as famosas APIs. Essa padronização permite ao desenvolvedor elaborar de forma mais fácil suas aplicações e APIs, visto que, a partir da adesão ao Restful, já temos a garantia de como serão desenvolvidas e consumidas as APIs.

Introdução

Antes de mais nada, Rest significa representational state transfer (transferência de estado representacional), que consiste em princípios que permitem a criação de um projeto com interfaces bem definidas. Ao adotar uma arquitetura que traz como base essa organização e definição de sua estrutura, todo o seu consumo e implementação acontecem de uma forma mais orgânica.

Mas espera aí, o artigo não é sobre Restful?

Calma! Eu explico. Existe uma certa confusão entre os dois termos, mas eles representam os mesmos princípios e a diferença entre eles é apenas gramatical, em outras palavras, sistemas que utilizam os princípios REST são chamados de RESTful. O Rest é o conjunto de princípios arquiteturais, já o Restful é a capacidade de um determinado sistema aplicar os princípios do Rest.

Aqui faremos uma pequena pausa no Restful para falar de APIs, que são um conjunto de rotinas e padrões estabelecidos e documentados por uma aplicação A, para que outras aplicações consigam utilizar funcionalidades desta aplicação A, sem precisar conhecer detalhes da implementação do software. Desta forma, entendemos que as APIs permitem uma interoperabilidade entre aplicações. Em outras palavras, a comunicação entre aplicações e entre os usuários.

A origem

O HTTP é o principal protocolo de comunicação para sistemas Web e existe há mais de 20 anos. Nos anos 2000, um dos principais autores do protocolo HTTP, Roy Fielding, sugeriu, dentre outras coisas, o uso de novos métodos HTTP, métodos estes que se propunham a resolver problemas relacionados à semântica quando requisições HTTP eram feitas.

Estas sugestões permitiram o uso do HTTP de uma forma mais próxima da nossa realidade, dando sentido às requisições HTTP conforme:

• GET http://www.meusite.com/usuarios
• DELETE http://www.meusite.com/usuarios/dailton
• POST http://www.meusite.com/usuarios –data {nome: tadashi}

É possível inferir que no primeiro caso estamos pegando (GET) todos os usuários do site, ou seja, teremos uma lista de todos os usuários que estão cadastrados. Já, no segundo caso, estamos apagando (DELETE) o usuário Dailton. No último exemplo, estamos usando o método POST, em que percebemos o envio de dados extras para cadastrar um novo usuário.

Endpoints

Como mostrado acima, seu serviço irá prover uma URL base e os verbos HTTP vão indicar qual ação está sendo requisitada pelo consumidor do serviço. Mas quais seriam esses verbos? Abaixo, os principais:

• Verbo GET: é usado para ler ou recuperar uma representação de um recurso.
• Verbo POST: é mais frequentemente utilizado para criar novos recursos.
• Verbo DELETE: é usado para excluir um recurso identificado por um URI.
• Verbo PUT: é mais utilizado para substituir (ou atualizar) recursos, executando a requisição para uma URI de recurso conhecido, com o corpo da requisição contendo a representação recém-atualizada do recurso original.
• Verbo PATCH: é usado para modificar parcialmente os recursos. A requisição só precisa conter as alterações específicas para o recurso, não o recurso completo.

Algumas dicas para padrão de nomenclatura.

• Dê preferência para o plural ao disponibilizar o resource. Utilize /users ao invés de /user.
• Se um recurso possui um nome composto utilize o “kebab-case”. Por exemplo Global Configuration seria GET /global-configuration.
• Dê preferência para URL’s em minúsculo, evite GET /Users, use GET /users.

Ações

Algumas vezes os endpoints não traduzem a complexidade do negócio. Nestes casos, especificar ações para os endpoints se fazem necessários. Convém reforçar que o uso de ações não fere o uso do padrão Rest.

Um exemplo da utilização de uma ação em um endpoint seria: 

http://www.meusite.com/usuarios/{1}/status

Documentação

O Open API é hoje o padrão mais utilizado para documentar API’s.

Sua implementação é relativamente simples em várias linguagens de programação. Além de documentar, ele disponibiliza também mecanismos para testar sua API no Browser.

Respostas

Quando o servidor recebe uma solicitação HTTP, o cliente deve saber o resultado da ação. Se houve sucesso ou falhou. Os códigos de status HTTP são vários códigos padronizados, com várias explicações em vários cenários. O servidor sempre deve retornar o código de status correto.

A seguir estão as categorias dos códigos HTTP:

• 2xx – Status de sucesso
• 3xx – Categoria de redirecionamento
• 4xx – Erro no Cliente
• 5xx – Erro no server

Resumo

Nesse artigo foi apresentado o Restful que é um padrão de arquitetura de software para criar e disponibilizar serviços na web. Listamos os seus principais verbos, como se criar uma ação, documentação e suas mensagem de retorno por categoria.

Referências