O que é RESTful

Vemos por ai varias vezes as palavras REST e RESTful. Vamos entender um pouco antes de começar.

REST (Representational State Transfer) É um conceito ou estilo arquitetural para construção de APIs.
- Define um conjunto de princípios que guiam a comunicação entre sistemas, como:
- Comunicação stateless (sem estado).
- Uso de métodos (Verbos) HTTP adequados (GET, POST, PUT, DELETE, etc.).
- Representação de recursos através de URIs.
- Suporte a diferentes formatos de dados (JSON, XML, etc.).
- HATEOAS (Hypermedia as the Engine of Application State) como um princípio avançado.
RESTful Refere-se a uma implementação prática e aderente aos princípios REST.
- Uma API é chamada de RESTful quando segue os princípios REST corretamente, como:
- Utilizar URIs claras e descritivas para representar recursos.
- Operar de forma stateless.
- Usar os métodos HTTP de forma consistente (ex.: GET para leitura, POST para criação, etc.).
- Retornar códigos de status HTTP apropriados (ex.: 200 OK, 404 Not Found).

REST é o conceito/estilo arquitetural. RESTful é a aplicação prática desse conceito em APIs. Se uma API não segue os princípios de REST, ela não pode ser chamada de RESTful.

Você pode implementar uma API baseada em conceitos REST sem ser completamente RESTful. Isso ocorre quando a API utiliza alguns dos princípios REST, mas não os implementa de forma correta ou completa.

Exemplos de APIs REST não RESTful

Métodos HTTP usados incorretamente: Uma API que usa apenas POST para todas as operações (leitura, criação, atualização e exclusão) não é RESTful, mesmo que use URLs e JSON. Exemplo:
```
POST /getUsers  
POST /createUser  
POST /deleteUser
```

Para ser RESTful, deve usar métodos adequados (GET, POST, PUT, DELETE).

Ausência de URIs claras e consistentes: URLs que não representam recursos de forma intuitiva, como:
```
/action?operation=getUser&id=1
```
Uma abordagem RESTful seria:
```
/users/1
```
Manter estado no servidor: APIs que dependem de sessões no servidor ou armazenam informações de contexto sobre o cliente entre as requisições quebram o princípio de ser stateless.
Ignorar códigos de status HTTP: Retornar sempre 200 OK com uma mensagem de erro no corpo, em vez de usar códigos apropriados como 404 Not Found ou 500 Internal Server Error.

Terminologia

Verbos ou HTTP Methods: GET PUT, POST DELETE
Messages - O payload de uma ação
URI - Uniform Resource Identifier.
- É uma string única que identifica um resource.
- Pode representar qualquer coisa: um documento, uma imagem, uma pessoa, ou até um conceito abstrato.
- Inclui dois tipos principais:
  - URL (Uniform Resource Locator) – Localiza um recurso.
  - URN (Uniform Resource Name) – Nomeia um recurso de maneira única, independentemente de sua localização.
- Exemplo:
  - https://example.com/document (URL, pois localiza o recurso).
  - urn:isbn:0451450523 (URN, pois nomeia um livro pelo ISBN, sem informar onde encontrá-lo).
URL - Uniform Resource Locator. É um subconjunto de URI.
- É um subconjunto de URI.
- Sempre descreve a localização de um recurso na internet.
- Inclui informações como:
  - O esquema/protocolo (ex.: http, https, ftp).
  - O endereço do recurso (ex.: example.com).
  - Opcionalmente, caminho, parâmetros e fragmentos (ex.: /page?id=10#section).
- Exemplo de URL:
  - https://example.com/document (informa como e onde acessar o documento).

Toda URL é uma URI, mas nem toda URI é uma URL.

Idempotência em RESTful refere-se a uma propriedade dos métodos HTTP onde múltiplas chamadas do mesmo método com os mesmos parâmetros/resultados não alteram o estado do recurso além do efeito inicial. Em outras palavras, você pode chamar a mesma operação várias vezes sem obter resultados diferentes ou causar efeitos colaterais adicionais.
- Operações GET devem ser consideradas idempotente pois não alteram nada no servidor.
Stateless significa que não guarda o estado e cada requisição enviada por um cliente a um servidor é independente e não depende de informações mantidas pelo servidor sobre requisições anteriores. Isso é uma característica fundamental de APIs RESTful e do protocolo HTTP.
- O fato de não guardar nada somente processar e devolver sempre torna escalável e simples.
- Cada requisição contém todas as informações necessárias para ser processada. Exemplo: Autenticação é geralmente enviada com cada requisição, por meio de um token ou cabeçalho Authorization.
HATEOAS (Hypermedia As The Engine of Application State) é um princípio da arquitetura RESTful que descreve como um cliente interage com um servidor através de hipermídia. A ideia central é que as respostas da API devem fornecer links para outros recursos ou ações possíveis, permitindo que o cliente navegue pelo sistema sem precisar conhecer todos os detalhes do seu funcionamento.
- Em vez de o cliente precisar conhecer todas as URLs disponíveis para interagir com a API, as respostas da API devem incluir links que indicam quais outras operações podem ser feitas a partir daquele ponto. Isso cria uma forma de navegação dinâmica dentro da aplicação, sem que o cliente tenha que fazer suposições sobre as rotas.
```
GET /users/1
```
O servidor responde com os dados do usuário, incluindo links para ações relacionadas:
```
Copy code
{
  "id": 1,
  "name": "David",
  "email": "[email protected]",
  "links": [
    { "rel": "self", "href": "/users/1" },
    { "rel": "orders", "href": "/users/1/orders" },
    { "rel": "update", "href": "/users/1/update" },
    { "rel": "delete", "href": "/users/1/delete" }
  ]
}
```

Exemplos de APIs REST não RESTful​

Terminologia​

Exemplos de APIs REST não RESTful

Terminologia