java-restify
, precisamos especificar os detalhes dos contratos: qual o path
, o verbo HTTP utilizado, o formato do corpo da requisição e da resposta, cabeçalhos, etc. Isso é feito com o uso de anotações.@Path
é utilizada para construção do path
do endpoint
. É obrigatória em todos os métodos. Se estiver presente no topo da classe, o conteúdo será concatenado à anotação do método.path
dinâmicamente, baseado nos parâmetros do método.path
tem duas partes variáveis, chamadas id e name, e o endpoint
será construído no momento da invocação do método, usando o valor fornecido para cada argumento. O binding
será realizado utilizando os nomes dos argumentos do método.Para permitir que os nomes dos parâmetros dos métodos sejam obtidos através de reflection, seu código deve ser compilado com a flag -parameters
binding
pelo nome dos argumentos, ou quiser associar a varíavel a um nome diferente do nome do parâmetro, é possível utilizar a anotação @PathParameter
:path
:Se nenhuma anotação for adicionada ao parâmetro, ele será considerado um@PathParameter
.
@Method
. Caso deseje utilizar algum outro método HTTP qualquer, também é possível utilizar essa anotação diretamente.@Header
pode ser utilizada para definição de headers
da requisição.@Header
do topo da interface e do método são unificadas no momento da construção da requisição. No exemplo acima, ao invocar o método findCustomerBy
, a requisição HTTP terá os cabeçalhos X-Custom-Header
(que será enviado em todos os métodos da interface) e Accept
.@Header
é repetível, e pode ser utilizada para informar vários cabeçalhos (no topo da interface ou por método):@HeaderParameter
:@Cookie
é utilizada para definição de cookies
da requisição, que são enviados através do cabeçalho Cookie.@Header
, cookies
podem ser definidos no topo da interface ou ao nível do método; cookies
dinâmicos também podem ser enviados através de argumentos do método anotados com @CookieParameter
.query parameters
, utilize a anotação @QueryParameter
:@QueryParameter
, mas existem outras alternativas, utilizando a anotação @QueryParameters
.Map<String, ?>
:String
, e os valores podem ser de qualquer tipo.Parameters
, um objeto Map-like que permite adicionar múltiplos valores por parâmetro:@BodyParameter
:@JsonContent
, o Content-Type da requisição será application/json
, e o objeto será serializado nesse formato se houver um converter registrado (consulte a documentação detalhada do mecanismo de serialização/deserialização e dos tipos de conteúdo suportados).@BodyParameter
.@Version
pode ser utilizada para indicar explicitamente a versão do endpoint
que está sendo consumido. A versão será incluída sempre antes do path
especificado para o método.path
, e sim através de algum cabeçalho da requisição. Nesse caso, é possível utiizar a anotação apenas para informar explicitamente a versão, sem incluí-la no path
:path
, ao header
ou ao query string
, é utilizado o método toString()
(argumentos com valores nulos são desconsiderados). Mas esse comportamento pode ser customizado através do atributo serializer
, presente nas anotações @PathParameter
, @HeaderParameter
, @CookieParameter
, @QueryParameter
e @QueryParameters
. Esse atributo recebe uma referência para uma implementação da interface ParameterSerializer
.Date
, mas queremos concatenar ao path
o timestamp. A estratégia padrão, usando o método toString()
, não atenderia esse caso de uso.