Se você pretende desenvolver um aplicativo mobile (iOS ou Android) e/ou um website que gerencia informações a partir de um banco de dados central, uma REST API talvez seja a melhor opção em termos de arquitetura para fazer essa comunicação entre o app e o servidor.

Se você parar para pensar em apps como Evernote e Wunderlist, eles podem ser desinstalados a qualquer momento e quando nós os instalamos novamente, todas as nossas informações são restaurados. Isso porque todos estes dados são armazenados em um banco de dados na nuvem e a comunicação entre o app e o banco de dados é feito através de uma REST API.

Neste breve post explico de maneira simples a arquitetura básica de uma REST API. A partir deste post você terá uma boa noção para partir para o segundo passo, que seria implementar de fato essa arquitetura na linguagem e banco de dados que desejar. Por exemplo, em PHP existem vários micro-frameworks prontos para se utilizar a arquitetura do REST como Slim, Lumen (tutorial aqui no blog) e Phalcon e banco de dados MySQL.

1. O que é uma REST API

REST é uma arquitetura de comunicação entre sistemas cliente/servidor. REST significa Representational State Transfer ou algo como Estado de Transferência Representacional (o nome é meio confuso mas fica tranquilo que você vai se sair bem). Implementar REST é muito simples em comparação com outras arquiteturas como SOAP, CORBA, WSDL, etc. Basicamente o REST se apóia no protocolo HTTP.

Pense numa REST API como um mordomo. Ele está ali para te obedecer. Você não se importa com a marca da cafeteira que ele vai usar, ou se tem detergente no seu estoque de produtos de limpeza. Você só quer que ele faça sua comida e leve até você, que deixe sua casa limpa, que chame um encanador pra arrumar sua torneira, enfim, como ele vai fazer isso não é seu problema, é dele. Você confia que ele vai fazer o que você pedir, e se por algum motivo ele não conseguir, vai te dar uma satisfação pelo menos.

É isso o que uma REST API representa. Uma única REST API pode fornecer informações e realizar tarefas especificas para um ou vários sistemas diferentes simultaneamente. Lembra do exemplo do Evernote que citei no começo do post? Existe uma REST API que fornece esses dados para o seu app do iPhone, para seu app desktop e para o site do Evernote ao mesmo tempo.

2. Design de uma REST API

A seguite algumas coisas que você precisa entender ao montar uma REST API:

» Métodos HTTP

Uma REST API bem planejada deveria suportar os métodos HTTP mais comuns (GET, POST, PUT e DELETE). Existem outros métodos HTTP como OPTIONS e HEAD mas não são muito utilizados e talvez você não precise deles. Cada método deve ser usado de acordo com o tipo de operação que estiver sendo realizada.

[table id=http-methods /]

» HTTP Status Code

Os códigos de status HTTP acompanham o corpo da resposta de toda requisição. Eles servem para informar a aplicação cliente qual ação que ela deve tomar. Por exemplo, se o código de status da resposta for 200, significa que o servidor conseguiu processar a requisição com sucesso, e portanto talvez o cliente queira fornecer uma resposta positiva para o usuário. Assim como se o código for 401, quer dizer que a requisição não foi autorizada, logo talvez o cliente queira informar isso ao usuário ou tomar alguma outra atitude. Uma causa muito comum de erros 401 ocorre quando o servidor não consegue autenticar o cliente, por exemplo por causa de uma api key inválida.

Note que não é obrigatório sua REST API suportar TODOS os códigos de status existentes, porém se ela puder ao menos suportar os mais utilizados, mencionados abaixo, estará de bom tamanho.

[table id=http-status /]

» Estrutura da URL

Na arquitetura REST o formato da URL deve ser facilmente compreendido. Cada URL para determinado recurso deve ser única. Se a sua REST API precisar de uma chave (api key) para autenticar, essa chave deve permanecer nos cabeçalhos (headers) do HTTP ao invés de incluí-los dentro da URL.

Por exemplo:
GET http://teste.com/v1/tarefas/11 – Vai te retornar os detalhes da tarefa cujo ID é 11

POST http://teste.com/v1/tarefas – Vai criar uma nova tarefa

» Versionamento da API

Existe muita discussão quanto se manter o número da versão da API na URL ou se dentro do header do HTTP. Mesmo que seja apropriado incluir a versão da API dentro dos headers, eu me sinto confortável em mantê-la na URL porque se torna conveniente para o lado do cliente para migrar de uma versão para outra de uma forma fácil e intuitiva.

Exemplo:
http://teste.com/v1/tarefas
http://teste.com/v2/tarefas

» Content Type

O Content Type é uma informação muito importante que vai no header do HTTP. Ele especifica qual o tipo de dados que está sendo transmitido entre o servidor e o cliente. Dependendo do típo de dados que sua API suporta, você precisa informar o Content Type.

Por exemplo, o tipo de dados JSON é informado assim: Content-Type: application/json, o XML assim: Content-Type: application/xml. Você encontra uma lista dos tipos de Content Type aqui

» API Key
Se a API que você está desenvolvendo for privada e precisa restringir ou limitar esse acesso, a melhor abordagem seria protege-la com uma chave, também chamada de API Key. Como o foco deste post é para iniciantes, não vou entrar a fundo em nada complexo. Por hora podemos supor que seu sistema irá gerar uma api key aleatória para cada usuário. Esta api key servirá para identificar o usuário e todas as suas ações só poderão afetar os recursos que pertencem a ele.

A API Key deve ser informada nos headers (propriedade Authorization).

Exemplo:

Authorization: tp78c093e452cq23caez68cmjls7e7q2

Perguntas Respondidas

[su_accordion]

[su_spoiler title=”REST e RESTful são a mesma coisa?”]Não. REST se refere a arquitetura em si e RESTful é um termo usado para indicar algumas ações da arquitetura REST. Podemos fizer que REST seria o substantivo e RESTful o adjetivo. Existem algumas arquiteturas que são parecidas e que usam algumas funcionalidades do REST e por isso costuma-se dizer que são arquiteturas RESTful, embora não sejam de fato uma arquitetura REST oficialmente.[/su_spoiler]

[su_spoiler title=”É obrigatório o uso de api keys ao desenvolver uma API REST?”]Não. Lembre-se que REST é apenas uma arquitetura. O desenvolvedor é quem fica a cargo de implementa-la da maneira que achar necessário. O uso de api keys são recomendadas para proteger a conexão contra acessos não autorizados.[/su_spoiler]

[su_spoiler title=”A arquitetura REST é melhor do que outras como SOAP e WSDL?”]A arquitetura REST é mais simples de ser implementada do que as outras. Em termos de segurança e performance, todas elas possuem suas próprias vantagens e desvantagens, por isso geralmente esses dois itens em si não são os que definem qual arquitetura se utilizar numa aplicação.[/su_spoiler]

[su_spoiler title=”É obrigatório implementar todos os métodos HTTP na minha REST API?”]Geralmente não. A lista oficial de métodos HTTP possui mais de 60 itens (lista completa aqui). Os que mencionei neste post são os mais utilizados na maioria das APIs de arquitetura REST.[/su_spoiler]

[/su_accordion]

Fabio Ferreira on EmailFabio Ferreira on InstagramFabio Ferreira on Twitter
Fabio Ferreira

Desenvolvedor Javascript e PHP, é editor do blog Café na Veia e também atua como desenvolvedor web freelancer na cidade de São Paulo.


Author: Fabio Ferreira

Desenvolvedor Javascript e PHP, é editor do blog Café na Veia e também atua como desenvolvedor web freelancer na cidade de São Paulo.

Deixe uma resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *

Instagram did not return any images.

Siga também nosso Instagram!