O que é RESTful?

1. O que é o estilo RES?
2. Por que usar o estilo REST?
3. Como projetar uma API estilo REST?
4. Caso

1. O que é o estilo RES?

REST é a sigla para Representational State Transfer, que significa transferência de estado representacional em chinês. REST descreve um sistema de rede de estilo arquitetônico, como aplicativos da web, REST não tem um padrão claro, mas mais como um estilo de design. Portanto, se uma arquitetura está em conformidade com o estilo REST, ela é chamada de arquitetura RESTful.

1.1 Recursos

REST significa transferência de estado representacional, então de quem é esse estado representacional? Um assunto está faltando aqui: recurso, e o significado completo é a transferência de estado representacional de recursos. Qualquer coisa que precise ser referenciada é um recurso. Este é um conceito muito amplo.Em aplicações Web, coisas que podem ser manipuladas através da Web são todos os recursos visíveis, como arquivos em disco e registros em bancos de dados. Em um aplicativo da Web, o identificador exclusivo de um recurso é o URI, que pode ser considerado como o endereço ou o nome do recurso.

O cliente usa GET, POST, PUT, DELETE, PATCH5 verbos que indicam modos de operação para operar os recursos do servidor: GET é usado para obter recursos, POST é usado para criar novos recursos (também pode ser usado para atualizar recursos), PUT é usado para atualizar recursos, e DELETE é usado para excluir recursos;

1.2 Recursos da Arquitetura REST

客户端 - 服务器: Ao separar as preocupações com a interface do usuário das preocupações com o armazenamento de dados, melhoramos a portabilidade das interfaces do usuário em várias plataformas e aumentamos a escalabilidade simplificando os componentes do servidor.
无状态: Cada solicitação do cliente ao servidor deve conter todas as informações necessárias para entender a solicitação e não deve utilizar nenhum contexto armazenado no servidor. Portanto, o estado da sessão é totalmente preservado no cliente.
可缓存: as restrições de cache exigem que os dados nas respostas às solicitações sejam marcados como armazenáveis em cache ou não, implícita ou explicitamente. Se a resposta puder ser armazenada em cache, o cache do cliente terá o direito de reutilizar esses dados de resposta para solicitações equivalentes posteriores.
统一接口: Ao aplicar princípios gerais de engenharia de software a interfaces de componentes, a arquitetura geral do sistema é simplificada e a visibilidade das interações é aprimorada. Para obter uma interface uniforme, várias restrições arquitetônicas são necessárias para orientar o comportamento dos componentes. O REST é definido por quatro restrições de interface: identificação de recursos; manipulação de recursos por meio de representações; informações autodescritivas; e hipermídia como o mecanismo do estado do aplicativo.
分层系统: o estilo de sistemas em camadas permite que uma arquitetura seja composta de camadas hierárquicas, restringindo o comportamento do componente de forma que cada componente não possa "ver" além da camada imediata com a qual eles interagem.
按需编码: REST permite estender a funcionalidade do cliente baixando e executando código na forma de applets ou scripts. Isso simplifica o cliente, reduzindo o número de funções necessárias para serem implementadas antecipadamente.

1.3 Comparação entre SOAP e REST

SOAP (Simple Object Access Protocol) é um protocolo simples para troca de informações em um ambiente descentralizado ou distribuído, e é um protocolo baseado em XML.

Blocos de construção:
Uma mensagem SOAP é um documento XML comum, que inclui os seguintes elementos:
(1) O elemento Envelope obrigatório, que pode representar este documento XML como uma mensagem SOAP;
(2) O elemento Header opcional, que contém informações de cabeçalho;
(3) O elemento Body obrigatório, que contém todas as mensagens de chamada e resposta;
(4) O elemento Fault opcional, que fornece informações sobre erros ocorridos durante o processamento desta mensagem;

Regras gramaticais:
(1) as mensagens SOAP devem ser codificadas em XML;
(2) as mensagens SOAP devem usar os namespaces SOAP Envelope e SOAP Encoding;
(3) as mensagens SOAP não podem conter referências DTD;
(4) não podem conter instruções de processamento XML;

REST é mais fácil de desenvolver porque aproveita o que já existe na web e tem liberdade limitada (menos opções para fazer, mais simples). O SOAP oferece muitas alternativas e é um pouco mais difícil de desenvolver, mas oferece mais alternativas e áreas de trabalho.

2. Por que usar o estilo REST?

A arquitetura RESTful pode fazer pleno uso de várias funções do protocolo HTTP, que é a melhor prática do protocolo HTTP.
A API RESTful é um estilo arquitetônico e de design de software, que pode tornar o software mais claro, mais conciso, mais hierárquico e de melhor manutenção.

GETSe não usarmos o estilo REST, usaremos apenas para obter recursos, adicionar e modificar recursos no código POST. Na verdade, o método HTTP tem seu significado único. Definimos a API de acordo com o estilo REST, que pode padronizar o método de acesso à interface, tornar a API mais concisa e clara e reduzir o tempo de comunicação do pessoal de front-end e back-end.

Se não for RESTful:

获取人员
GET: /epam/user/getUserById?id=1

保存人员
POST: /epam/user/saveUser

删除人员
POST: /epam/user/deleteUserById?id=1

Usando RESTful:

获取人员
GET: /epam/users/:id

创建人员
POST: /epam/users

修改人员全部信息
PUT: /epam/users/:id

修改人员部分信息
PATCH: /epam/users/:id

删除人员
DELETE: /epam/user/:id

3. Como projetar uma API estilo REST?

1 solicitação de API RESTful

Solicitação de API RESTful = verbo + objeto

Verbos: Use cinco métodos HTTP, correspondentes a operações CRUD.
Objeto: todos os URLs devem usar substantivos plurais, com exceções. Por exemplo, uma pesquisa mais intuitiva pode ser usada para pesquisar.
Informações de filtragem (filtragem): Se o número de registros for grande, a API deve fornecer parâmetros para filtrar os resultados retornados. ?limit=10 especifica o número de registros retornados. ?offset=10 especifica a posição inicial dos registros retornados.

1.1 Verbos HTTP

GET：   读取（Read）
POST：  新建（Create）
PUT：   更新（Update）
PATCH： 更新（Update），通常是部分更新
DELETE：删除（Delete）

1.2 URL (objeto) deve ser um substantivo

O objeto é a URL da API, na qual o verbo HTTP atua. Deve ser um substantivo, não um verbo. Por exemplo, o URL /artigos está correto, mas os URLs a seguir não são substantivos, então estão todos errados.

/getAllCars
/createNewCar
/deleteAllRedCars

Como URLs são substantivos, é recomendável usar plurais para uniformidade.

1.3 Filtragem de informações (Filtragem)

Se o número de registros for grande, é impossível que o servidor retorne todos para o usuário. A API deve fornecer parâmetros e filtrar os resultados retornados.

Abaixo estão alguns parâmetros comuns.

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

2 respostas de API RESTful

Para cada solicitação do cliente, o servidor deve responder. A resposta consiste em HTTP 状态码e 数据duas partes.
Quando o cliente solicita, ele deve informar claramente ao servidor para aceitar o formato JSON e o atributo ACCEPT do cabeçalho HTTP da solicitação deve ser definido como application/json
Os dados retornados pelo servidor não devem ser texto simples, mas um arquivo JSON对象. O atributo Content-Type do cabeçalho HTTP respondido pelo servidor deve ser definido comoapplication/json
Tratamento de erro Se o código de status for 4xx, uma mensagem de erro deve ser retornada ao usuário. De um modo geral, o erro é usado como o nome da chave nas informações retornadas e a mensagem de erro é usada como o valor da chave. {erro: "Chave de API inválida"}
A API RESTful de autenticação deve ser sem estado, cada solicitação deve conter algumas credenciais de autenticação

2.1 Códigos de status HTTP comumente usados

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

2.2 dados de retorno

O corpo da resposta são os dados diretamente, portanto, não faça empacotamento redundante. instância de erro:

{
    
    "success":true, "data":{
    
    "id":1, "name":"周伯通"} }

Uma abordagem inadequada é retornar um código de status 200 mesmo se ocorrer um erro e colocar as informações de erro no corpo dos dados, conforme mostrado abaixo.

{
    
    "status": "failure", "data": {
    
     "error": "Expected at least two items in list."} }

A abordagem correta é que o código de status reflita o erro ocorrido e as informações de erro específicas sejam retornadas no corpo dos dados. Abaixo está um exemplo.

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    
    
  "error": "Invalid payoad.",
  "detail": {
    
    
    "surname": "This field is required."
  }
}

3 Modelo de Maturidade de Richardson

Leonard Richardson analisou centenas de projetos de serviços da Web diferentes e os dividiu em quatro categorias com base em sua compatibilidade com REST. Este modelo de divisão de serviços REST é utilizado para identificar seu nível de maturidade, conhecido como modelo de maturidade de Richardson.

Richardson usa três fatores para determinar a maturidade de um serviço, ou seja, URI, método HTTP e HATEOAS (hipermídia). Quanto mais dessas tecnologias um serviço adota, mais maduro ele é considerado. Richardson divide esses níveis de maturidade em quatro graus: zero, um, dois e três.

Referência: Modelo de Maturidade de Richardson

3.1 Nível zero

Não use nenhum URI, método HTTP e função HATEOAS, HTTP é usado apenas como protocolo para transmissão remota, para obter e enviar dados, envie a solicitação para o mesmo URI e use apenas o método POST.

Exemplo: Use o mesmo URI e método para obter e salvar dados

Obter usuário: POST http://epam/user
Salvar usuário:POST http://epam/user

3.2 Nível 1

Use URI, método HTTP e URI em HATEOAS. Quando uma API pode distinguir diferentes recursos, ela usa vários URIs. Cada URI é uma entrada de recurso específica, mas ainda assim apenas o método POST pode ser usado.

Exemplo:
lista de pessoas: POST http://epam/users
uma pessoa:POST http://epam/users/0003

3.3 Secundário

Usando URI, método HTTP e URI e HTTP no HATEOAS, o verbo HTTP correto é usado para cada solicitação, sugere que, para ser verdadeiramente RESTful, os verbos HTTP devem ser usados na API e, para cada solicitação, a resposta HTTP correta código é retornado.

获取人员  GET: /epam/users/:id ，获取的到返回200，没有则返回404

创建人员  POST: /epam/users

删除人员  DELETE: /epam/user/:id

3.4 Nível 3

Usando todos os três, URI, HTTP e HATEOAS, é uma combinação de secundário e HATEOAS. A hipermídia contém links URI para outros recursos nos quais o cliente pode estar interessado. Seu foco é nos dizer o que fazer a seguir e o URI do recurso no qual precisamos operar.

4. Caso

根据ID获取整个人员信息
GET: /epam/users/:id

根据ID获取人员地址信息
GET: /epam/users/:id/address

人员列表
GET: /epam/users

人员分页列表，根据name升序
GET: /epam/users?size=20&page=5&sortby=name&order=asc

创建人员
POST: /epam/users

修改人员全部信息
PUT: /epam/users/:id

修改人员部分信息
PATCH: /epam/users/:id

删除人员
DELETE: /epam/user/:id

Referências
https://restfulapi.cn/
https://www.ruanyifeng.com/blog/2014/05/restful_api.html

SpringBoot Tutorial (16) O que é RESTful?