Sabe-se que atualmente (2019) boa parte das aplicações, empresas e serviços se comunicam através de APIs, que não nada mais são que serviços expostos na internet para consumo de terceiros. Permitindo facilmente que o mesmo serviço possa ser consumido por um aplicativo móvel, um site de internet ou um aplicativo em seu desktop, desde que tenha acesso à internet.
Futuramente iremos debater sobre outros meios de comunicação e integração como SOAP e GraphQL, mas vamos do princípio mais básico.
O que é REST?
REST é um acrônimo para REpresentational State Transfer, ou seja, Transferência de Representação de Estado. Que nada mais é do que troca de informações utilizando o protocolo HTTP.
Um pouco de HTTP
As requisições feitas por uma RESTful API são através do protocolo HTTP onde temos:
– Endpoint: endereço do serviço
– Verbo HTTP: ação a ser tomada a partir do endpoint
– Payload: corpo da requisição podendo ser JSON ou XML
Dentre os verbos / métodos possíveis: Referência
GET
O métodoGET
solicita a representação de um recurso específico. Requisições utilizando o métodoGET
devem retornar apenas dados.HEAD
O métodoHEAD
solicita uma resposta de forma idêntica ao métodoGET
, porém sem conter o corpo da resposta.POST
O métodoPOST
é utilizado para submeter uma entidade a um recurso específico, frequentemente causando uma mudança no estado do recurso ou efeitos colaterais no servidor.PUT
O métodoPUT
substitui todas as atuais representações do recurso de destino pela carga de dados da requisição.DELETE
O métodoDELETE
remove um recurso específico.CONNECT
O métodoCONNECT
estabelece um túnel para o servidor identificado pelo recurso de destino.OPTIONS
O métodoOPTIONS
é usado para descrever as opções de comunicação com o recurso de destino.TRACE
O métodoTRACE
executa um teste de chamada loop-back junto com o caminho para o recurso de destino.PATCH
O métodoPATCH
é utilizado para aplicar modificações parciais em um recurso.
HTTP Status, toda requisição HTTP retorna seu código de status nos avisando se a requisição foi processada com sucesso, se teve retorno, se deu algum tipo de erro e etc. Estes códigos apesar de programáveis (seu backend pode definir que tipo de HTTP Code retornar), são ótimos indícios de como sua API se comporta.
Exemplo:
> 1xx Informativo
> 2xx Sucesso
> 3xx Redirecionamento
> 4xx Erro lado do cliente
> 5xx Erro lado do servidor
Referência completa: Link
JSON x XML
É possível utilizar tanto XML quando JSON para requisições ou respostas em serviços REST. Porém comumente o uso de JSON por ser muito mais leve e de fácil entendimento, leitura e menos verboso que XML. Mas não há uma regra e sim varia conforme a necessidade de sua aplicação ou cliente.
//JSON de Cliente
{
name: 'John',
age: 33,
gender: 'M'
children: [
{
name: 'Mike',
age: 5,
gender: 'M'
}
]
};
//XML de Cliente (Forma Representativa)
<client>
<name>John</name>
<age>33</age>
<gender>M</gender>
<children>
<child>
<name>Mike</name>
<age>5</age>
<gender>M</gender>
</child>
</children>
</client>
REST x RESTful
De uma forma bem resumida, podemos dizer que REST é o conceito arquitetural e RESTful é forma de aplicar este conceito de forma prática.
RESTful API
Uma vez definido nosso endpoint lá no backend, utilizaremos (tese) este mesmo endpoint para operações diferentes dentro da nossa aplicação e a melhor forma de exemplificar é utilizando serviço de CRUD.
http://{my-app.com}/api/{domain}
Seguindo o exemplo acima digamos que seu domínio seja de Cliente e partir dai queremos executar determinada operação através dos verbos disponíveis, olha que prático:
GET: http://{my-app.com}/api/client //listar todos
GET: http://{my-app.com}/api/client/{id} // recuperar por id
DELETE: http://{my-app.com}/api/client/{id} // remove client por id
PUT: http://{my-app.com}/api/client //atualizar, porém é necessário body com os dados cliente
POST: http://{my-app.com}/api/client //salvar, porém é necessário body com os dados cliente
Exemplo de payload em JSON:
const client: Client = {
name: 'John',
age: 33,
role: 'user',
gender: 'M'
};
Resumo
Espero ter ajudado em dar um overview sobre conceitos básicos e práticos de REST, HTTP com REST, RESTful, JSON. Em um futuro próximo faremos alguns tutorias para consolidar o conceito com a prática real. Mas antes de fazer tutoriais é necessário saber o porque está usando aquela abordagem, se realmente se aplica ao cenário que está enfrentando e por ai. Até a próxima!