Skip to content

O que é uma API REST e como implementar uma?

Jump to bottom
Claudia Melo edited this page May 10, 2018 · 3 revisions

O que é uma API?

O acrônimo API que provém do inglês Application Programming Interface (Interface de Programação de Aplicações), trata-se de um conjunto de rotinas e padrões estabelecidos e documentados por uma aplicação A, para que outras aplicações consigam utilizar as funcionalidades desta aplicação A, sem precisar conhecer detalhes da implementação do software.

Basicamente uma aplicação oferece serviços através de uma interface com a qual podemos interagir sem precisar saber dos detalhes de implementação daquela aplicação.

Como uma API abstrai as informações do lado Servidor para o mundo Cliente (website, apps etc)

Exemplos de API: Instagram, Spotify, Google Maps, etc.

O que é REST?

REST ou Representational State Transfer (Transferência de Estado Representacional) é um modelo utilizado para se projetar arquiteturas de software distribuído, baseadas em comunicação via rede, proposto por Roy Fielding, um dos principais criadores do protocolo HTTP, em sua tese de doutorado e que foi adotado como o modelo a ser utilizado na evolução da arquitetura do protocolo HTTP. Assim, REST foi adotado e definido oficialmente pela W3C.

Falando de maneira mais simples, o REST consiste em princípios que, quando seguidos, permitem a criação de um projeto com interfaces bem definidas, o que, por exemplo, permite que aplicações se comuniquem de maneira mais fácil.

O REST ignora os detalhes da implementação de componente e a sintaxe de protocolo com o objetivo de focar nos papéis dos componentes, nas restrições sobre sua interação com outros componentes e na sua interpretação de elementos de dados significantes.

Quer ver o conceito em imagens? Dê uma olhada nesta apresentação sobre REST.

Princípios para implementar uma API REST

Vamos ver quais princípios seguir para criar uma API que siga o REST.

Identificação de Recursos

Toda aplicação gerencia algumas informações. Uma aplicação de um E-commerce, por exemplo, gerencia seus produtos, clientes, vendas, etc. Essas "coisas" que uma aplicação gerencia são chamadas de Recursos no modelo REST.

Um recurso nada mais é do que uma abstração sobre um determinado tipo de informação que uma aplicação gerencia, sendo que um dos princípios do REST diz que todo recurso deve possuir uma identificação única. Essa identificação serve para que a aplicação consiga diferenciar qual dos recursos deve ser manipulado em uma determinada solicitação.

Imagine a seguinte situação: Você desenvolveu um Web Service REST que gerencia seis tipos de recursos. Os clientes desse Web Service manipulam esses recursos via requisições HTTP. Ao chegar uma requisição para o Web Service, como ele saberá qual dos recursos deve ser manipulado? É justamente por isso que os recursos devem possuir uma identificação única, que deve ser informada nas requisições.

A identificação do recurso deve ser feita utilizando-se o conceito de URI (Uniform Resource Identifier), que é um dos padrões utilizados pela Web. Alguns exemplos de URI’s:

As URI’s são a interface de utilização dos seus serviços e funcionam como um contrato que será utilizado pelos clientes para acessá-los. Vejamos agora algumas boas práticas no uso de URI’s.

Utilize URI’s legíveis

Ao definir uma URI, utilize nomes legíveis por humanos, que sejam de fácil dedução e que estejam relacionados com o domínio da aplicação. Isso facilita a vida dos clientes que utilizarão o serviço, além de reduzir a necessidade de documentações extensas.

Utilize o mesmo padrão de URI na identificação dos recursos Mantenha a consistência na definição das URI’s. Crie um padrão de nomenclatura para as URI’s dos recursos e utilize sempre esse mesmo padrão. Evite situações como:

Evite adicionar na URI a operação a ser realizada no recurso

Os recursos que uma aplicação gerencia podem ser manipulados de diversas maneiras, sendo para isso disponibilizada algumas operações para manipula-los, tais como: criar, listar, excluir, atualizar, etc.

A manipulação dos recursos deve ser feita utilizando-se os métodos do protocolo HTTP, que inclusive é um dos princípios do REST que será discutido mais adiante.

Portanto, evite definir URI’s que contenham a operação a ser realizada em um recurso, tais como:

Evite adicionar na URI o formato desejado da representação do recurso

É comum que um serviço REST suporte múltiplos formatos para representar seus recursos, tais como XML, JSON e HTML. A informação sobre qual o formato desejado por um cliente ao consultar um serviço REST deve ser feita via Content Negotiation, conforme será mostrado mais adiante.

Portanto, evite definir URI’s que contenham o formato desejado de um recurso, tais como:

Evite alterações nas URI’s

A URI é a porta de entrada de um serviço. Se você a altera, isso certamente causará impacto nos clientes que estavam a utilizando, pois você alterou a forma de acesso a ele. Após definir uma URI e disponibilizar a manipulação de um recurso por ela, evite ao máximo sua alteração.

Nos casos mais críticos, no qual realmente uma URI precisará ser alterada, notifique os clientes desse serviço previamente. Verifique também a possibilidade de se manter a URI antiga, fazendo um redirecionamento para a nova URI.

Utilização dos métodos HTTP para manipulação dos recursos

Os recursos gerenciados por uma aplicação, e identificados unicamente por meio de sua URI, geralmente podem ser manipulados de diversas maneiras. É possível criá-los, atualizá-los, excluí-los, dentre outras operações.

Quando um cliente dispara uma requisição HTTP para um serviço, além da URI que identifica quais recursos ele pretende manipular, é necessário que ele também informe o tipo de manipulação que deseja realizar no recurso. É justamente aí que entra um outro conceito da Web, que são os métodos do protocolo HTTP.

O protocolo HTTP possui diversos métodos, sendo que cada um possui uma semântica distinta, e devem ser utilizados para indicar o tipo de manipulação a ser realizada em um determinado recurso.

Vejamos agora os principais métodos do protocolo HTTP e o cenário de utilização de cada um deles:

Método HTTP Semântica
GET Obter os dados de um recurso.
POST Criar um novo recurso.
PUT Substituir os dados de um determinado recurso.
PATCH Atualizar parcialmente um determinado recurso.
DELETE Excluir um determinado recurso.
HEAD Similar ao GET, mas utilizado apenas para se obter os cabeçalhos de resposta, sem os dados em si.
OPTIONS Obter quais manipulações podem ser realizadas em um determinado recurso.

Geralmente as aplicações apenas utilizam os métodos GET, POST, PUT e DELETE, mas se fizer sentido em sua aplicação utilizar algum dos outros métodos, não há nenhum problema nisso.

Veja a seguir o padrão de utilização dos métodos HTTP em um serviço REST, que é utilizado pela maioria das aplicações e pode ser considerado uma boa prática. Como exemplo será utilizado um recurso chamado Cliente.

Método URI Utilização
GET /clientes Recuperar os dados de todos os clientes.
GET /clientes/id Recuperar os dados de um determinado cliente.
POST /clientes Criar um novo cliente.
PUT /clientes/id Atualizar os dados de um determinado cliente.
DELETE /clientes/id Excluir um determinado cliente.

Como boa prática, em relação aos métodos do protocolo HTTP, evite utilizar apenas o método POST nas requisições que alteram o estado no servidor, tais como: cadastro, alteração e exclusão, e principalmente, evite utilizar o método GET nesses tipos de operações, pois é comum os navegadores fazerem cache de requisições GET, as disparando antes mesmo do usuário clicar em botões e links em uma pagina HTML.

Representações dos recursos

Os recursos ficam armazenados pela aplicação que os gerencia. Quando são solicitados pelas aplicações clientes, por exemplo em uma requisição do tipo GET, eles não “abandonam” o servidor, como se tivessem sido transferidos para os clientes. Na verdade, o que é transferido para a aplicação cliente é apenas uma representação do recurso.

Um recurso pode ser representado de diversas maneiras, utilizando-se formatos específicos, tais como XML, JSON, HTML, CSV, dentre outros. Exemplo de representação de um recurso no formato XML.

<cliente>
  <nome>Rodrigo</nome>
  <email>[email protected]</email>
  <sexo>Masculino</sexo>
  <endereco>
    <cidade>Brasilia</cidade>
    <uf>DF</uf>
  </endereco>
</cliente>

A comunicação entre as aplicações é feita via transferência de representações dos recursos a serem manipulados. Uma representação pode ser também considerada como a indicação do estado atual de determinado recurso.

Essa comunicação feita via transferência de representações dos recursos gera um desacoplamento entre o cliente e o servidor, algo que facilita bastante a manutenção das aplicações.

Suporte diferentes representações

É considerada uma boa prática o suporte a múltiplas representações em um serviço REST, pois isso facilita a inclusão de novos clientes. Ao suportar apenas um tipo de formato, um serviço REST limita seus clientes, que deverão se adaptar para conseguir se comunicar com ele.

Os três principais formatos suportados pela maioria dos serviços REST são:

  • HTML;
  • XML;
  • JSON.

Conclusão

REST não é algo complicado, é conjunto de alguns poucos princípios e restrições que quando aplicados garantem características importantes para aplicações e serviços, tais como: portabilidade, escalabilidade e desacoplamento. Sua utilização é grande na construção de APIs na web, devido as benefícios que traz.

Existem alguns outros princípios e detalhes que podem ser observados, mas quis deixar os principais listados acima. Se você quer continuar tiver interesse em entender um pouco mais recomendo a leitura de qualquer das fontes deixadas abaixo, principalmente a da caelum que foi de onde tirei toda a parte dos princípios, pois está explicada de maneira bem simples.

Fontes

Clone this wiki locally