A - Verbos/Métodos disponíveis (@annotation)

O modo mais simples de utilizar e quais verbos/métodos o serviço REST irá responder é através de Annotations.

A utilização do recurso de annotations na linguagem TL++ possibilitou a simplificação da escrita nas aplicações REST.

Os verbos/métodos HTTP comuns utilizados nestes tipos de requisições já estão com as suas respectivas annotations configuradas prontas para serem utilizadas.

Atualmente, temos disponíveis os verbos/métodos mais usados em serviços REST, sendo:

• GET
  O método GET solicita a representação de um recurso específico. Requisições utilizando o método GET devem retornar apenas dados.
  
  

• POST
  O método POST é utilizado para adicionar recursos no servidor REST. Se for um serviço que seja o cadastro de clientes, o método POST irá criar um registro novo referente a um cliente novo.
  

• PUT
  O método PUT modifica um recurso existente no servidor. Na semântica usada em modo geral, pelo método PUT enviamos todos os dados do recurso, independentemente se serão modificados somente partes dos dados.
  
  

• PATCH
  O método PATCH modifica um recurso existente no servidor. Na semântica usada em modo geral, pelo método PATCH enviamos somente os dados que serão modificados.
  
  

• DELETE
  O método DELETE é usado para apagar um recurso no servidor REST.
  
  

Nota: Embora os métodos PUT e PATCH sejam usados semanticamente de forma diferentes, tecnicamente não há exigência para que as aplicações serem implementadas desse modo.

Existem implementações que utilizam Criar e Modificar recursos através de um único método, ou seja, POST, PUT e PATCH são usados através, por exemplo, do método POST e o tratamento é feito na lógica implementada no servidor.

Embora não esteja de acordo com a semântica proposta, não significa que esteja errado.

A annotation utiliza duas propriedades, embora somente 1 é essencial para o funcionamento do serviço, sendo:

• endpoint Essa propriedade é obrigatória e é responsável para definir o endpoint utilizado na URL para que o usuário possa fazer uma requisição ao serviço.

• description É somente a descrição, não é obrigatória e tem a finalidade somente para escrever para que ser o serviço.

Abaixo iremos exemplificar um método GET, informando todas as propriedades, e somente a endpoint em suas duas formas.

#include "tlpp-core.th"
#include "tlpp-rest.th"
​
/*
Exemplo 01
​
Informamos as duas propriedades.
Note que nesse modo, é obrigatório informar nominalmente as propriedades.
*/
@Get( endpoint="sample/full", description='exemplo usando as duas propriedades' )
user function sampleFull()
​
    ......
    
    oRest:setResponse(cJson)
return
​
        
/*
Exemplo 02
​
Informamos somente endpoint, que é obrigatória.
Note que informamos nominalmente a propriedade.
*/
@Get( endpoint="sample/onlyEndpoint1" )
user function sampleOnlyEndpoint1()
​
    ......
    
    oRest:setResponse(cJson)
return
  
        
/*
Exemplo 03
​
Informamos somente endpoint, que é obrigatória.
Note que informamos NÃO nominalmente a propriedade, esse é modo mais simples de utilizar a annotation, pois irá atribuir o valor informado automaticamente para o endpoint.
*/
@Get( "sample/onlyEndpoint2" )
user function sampleOnlyEndpoint2()
​
    ......
    
    oRest:setResponse(cJson)
return
​
​

Abaixo é possível saber mais sobre cada verbo/método: