Rest - Muito além de enviar JSON (PT-1).

Como desenvolvedores, com o tempo desejamos nos aprofundar ainda mais nas ferramentas e produtos que desenvolvemos.

Comigo não foi diferente, de uns tempos pra cá, eu senti uma necessidade de aprofundar meus conhecimentos e decidi começar por essa arquitetura que, embora eu desenvolva a um tempo razoável, fui aprender conceitos importantes recentemente. E gostaria de deixar por escrito isso.

Afinal, que Diabos é REST?

REST Significa Representational State Transfer, ou traduzindo para o bom e velho português, Transferência de Estado Representacional. Se trata de uma arquitetura usada para web que foi idealizada por Roy Fielding, um dos principais criadores do protocolo HTTP. O Rest define algumas regras para que a comunicação entre sistemas ocorra de forma mais simples e padronizada.
Existem vários artigos na internet que explicam com mais detalhes as características e os principais métodos utilizados quando usamos REST em nossas APIs.
Eu vou entrar aqui nessa primeira parte sobre algo relacionado a REST que particularmente foi uma novidade pra mim e pode ser pra muitos desenvolvedores. Que é o Method Negotiation.

Method Negotiation - Nunca vi, nem cumi, só ouço falar.

Além dos conhecidos Métodos http, GET,POST,PUT,PATH,DELETE, existe um método que é bastante útil para tornar sua API rest um pouco mais robusta, que o método OPTIONS.

O Método options é usado quando não sabemos quais os verbos HTTP estão disponíveis para um endpoint específico. Nesse caso quando usamos esse método, o servidor nos responde com os métodos que são aceitos naquele endpoint. Claro que, para que nossa API possa responder dessa forma, precisamos realizar a implementação, e essa pode ser feita de forma geral onde respondemos todos os verbos HTTP aceitos em nossa API ou podemos criar um método OPTIONS para cada endpoint.
Veja esse exemplo:

Implementação de um endpoint que responde ao OPTIONS (Estou usando Symfony PHP):

Como vimos no print acima, implementar um método OPTIONS é algo bem simples. No exemplo acima estou usando PHP/Symfony. Se trata de um método dentro de uma classe Controller onde existe um metodo que responde a url '/room' , porém nesse caso ai estou dizendo que ele responde ao método http OPTIONS. Dentro da função eu apenas instancio um objeto Response e defino dentro do cabeçalho de resposta através da chave Allow que esse endpoint permite apenas POST e OPTIONS. Quando realizamos uma requisição para esse endpoint recebemos a seguinte resposta:

Como podem ver dentro do cabeçalho de resposta, veio informando justamente quais são os métodos que são suportados para o endpoint solicitado.

Através desse exemplo simples podemos ver como aplicar o metodo OPTIONS e assim realizar o Method Negotiation.

Mas vamos supor que você construiu seu endpoint e ele foi desenvolvido para receber no corpo da requisição dados no formato JSON, mas o cliente que está usando a sua API, envia no corpo da requisição XML. O que você faz nessa situação? Sua API simplesmente quebra e devolve uma mensagem de erro?
Existe uma forma melhor de lidar com isso, usando outro conceito muito interessante do REST que é o Content Negotiation. A parte 2 desse artigo vai abordar esse tema.