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

• GETO método GET solicita a representação de um recurso específico. Requisições utilizando o método GET devem retornar apenas dados.
• HEAD O método HEAD solicita uma resposta de forma idêntica ao método GET, porém sem conter o corpo da resposta.
• POST O método POST é 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étodo PUT substitui todas as atuais representações do recurso de destino pela carga de dados da requisição.
• DELETEO método DELETE remove um recurso específico.
• CONNECT O método CONNECT estabelece um túnel para o servidor identificado pelo recurso de destino.
• OPTIONSO método OPTIONS é usado para descrever as opções de comunicação com o recurso de destino.
• TRACE O método TRACE executa um teste de chamada loop-back junto com o caminho para o recurso de destino.
• PATCHO método PATCH é 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!