Arquitetura Rest API no Liquido

A arquitetura Rest API é uma abordagem popular para o desenvolvimento de aplicações web por promover o desacoplamento entre cliente e servidor. Assim, garantindo maior flexibilidade e escalabilidade.

Conceitos

REST (Transferência de Estado Representacional, ou Representational State Transfer)

Essa arquitetura de software que utiliza protocolos e padrões da web, como HTTP, para criar serviços web. Os principais princípios do REST incluem:

• Sem estado (Stateless): cada requisição do cliente para o servidor deve conter todas as informações necessárias para entender e processar a requisição. O servidor não deve armazenar informações sobre o estado do cliente entre as requisições.
• Recursos: os recursos são identificados por URLs (Uniform Resource Locators, ou localizadores uniformes de recursos). Onde recursos são tudo o que é disponibilizado pelo servidor, como dados, serviços ou funcionalidades.
• Métodos HTTP: o REST utiliza os métodos HTTP (GET, POST, PUT, DELETE, etc.) para realizar operações sobre os recursos.
• Representações: os recursos podem ter diferentes representações, como JSON, XML, HTML, etc. O cliente pode solicitar uma representação específica por meio do cabeçalho “Accept” na requisição HTTP.
• HATEOAS (Hipermídia como o Motor do Estado da Aplicação, ou Hypermedia as the Engine of Application State): o cliente deve conseguir navegar pelos recursos da API utilizando links fornecidos nas respostas do servidor.

API (Interface de Programação de Aplicações, ou Application Programming Interface)

É uma forma de disponibilizar funcionalidades e dados de um sistema, criando uma interface que pode ser utilizada por outras aplicações, independentemente da linguagem de programação ou plataforma. As APIs REST são amplamente utilizadas para criar serviços web que podem ser consumidos por diferentes tipos de clientes, como aplicativos móveis, aplicações web, entre outros.

Serialização

A serialização é o processo de converter um objeto ou estrutura de dados em um formato que pode ser facilmente armazenado ou transmitido, como, por exemplo, JSON, YAML e XML. No contexto de APIs REST, a serialização é usada para transformar os dados do servidor em um formato que pode ser enviado ao cliente e vice-versa. No Liquido, podemos utilizar a serialização para converter objetos em JSON, facilitando a comunicação entre o cliente e o servidor. Veja um exemplo simples de serialização em Liquido:

liquido.rotaGet(funcao(requisicao, resposta) {
    resposta.json([{
        "id": 1,
        "titulo": "teste 1",
        "descricao": "descricao 1"
    }])
})

No exemplo acima, definimos uma rota GET que retorna uma lista de objetos em formato JSON. A função resposta.json é usada para serializar os dados e enviá-los ao cliente. Note que usamos aspas duplas para definir as chaves e valores dos objetos JSON, conforme a especificação do JSON. Isso gerará a seguinte resposta:

[
    {
        "id": 1,
        "titulo": "teste 1",
        "descricao": "descricao 1"
    }
]

Autodocumentação

Para projetos REST, Liquido possui capacidades de autodocumentação, ou seja, gerar uma série de documentos que explicam como a API REST que você está escrevendo irá funcionar.

Uma boa parte dos elementos são depreendidos pelo método de rota usado, o tipo de retorno usado para a resposta, e assim por diante. Outros podem ser adicionados por decoradores. Veja um exemplo de rota:

liquido.rotaGet(funcao(requisicao, resposta) {
    resposta.json([{
        "id": 1,
        "titulo": "teste 1",
        "descricao": "descricao 1"
    }])
})

• Sabemos a rota pela posição do arquivo controlador na estrutura de diretórios;
• Sabemos que a rota responde pelo método GET;
• Sabemos que o tipo da resposta é feito por resposta.json(), portanto, um conteúdo JSON.

Nosso modelo de auto-documentação é o OpenAPI 3.1.0. A geração dessa documentação pode ser feita de duas maneiras:

• Na inicialização do servidor;
• Por linha de comando.

Decoradores para auto-documentação

Os decoradores suportados atualmente estão como no exemplo abaixo:

@rest.documentacao(
    sumario = "Um exemplo de rota GET.", 
    descricao = "Uma descrição mais detalhada sobre como a rota GET funciona.", 
    idOperacao = "lerArtigos",
    etiquetas = ["artigos"]
)
@rest.resposta(
    codigo = 200, 
    descricao = "Devolvido com sucesso", 
    formatos = ["application/json", "application/xml"]
)
liquido.rotaGet(funcao(requisicao, resposta) {
    resposta.json([{
        "id": 1,
        "titulo": "teste 1",
        "descricao": "descricao 1"
    }])
})