Início rápido

O funcionamento do java-restify é baseado em proxies de interfaces.

Primeiro, precisamos de uma interface Java para abstrair a API que desejamos consumir. Com o uso de algumas anotações, podemos representar os detalhes das requisições HTTP.

import com.github.ljtfreitas.restify.http.contract.Path;
import com.github.ljtfreitas.restify.http.contract.Get;
import com.github.ljtfreitas.restify.http.contract.Post;
import com.github.ljtfreitas.restify.http.contract.BodyParameter;
import com.github.ljtfreitas.restify.http.contract.PathParameter;

@Path("http://whatever.api.com")
public interface WhateverApi {

  @Path("/resource") @Get
  String getResource();

  @Path("/resource/{id}") @Get
  String getResourceById(@PathParameter("id") String id);

  @Path("/resource") @Post
  String createResource(@BodyParameter String content);
}

Os métodos da interface acima irão se comportar da seguinte maneira:

• o método getResource irá realizar uma chamada HTTP GET para a URL http://whatever.api.com/resource

• o método getResourceById irá realizar uma chamada HTTP GET para a URL http://whatever.api.com/resource/{id}, sendo que o placeholder "{id}" será substituído pelo valor do parâmetro anotado com @PathParameter.

• o método createResource irá realizar uma chamada HTTP POST para a URL http://whatever.api.com/resource, e o valor do parâmetro anotado com @BodyParameter será enviado no corpo da requisição.

Agora, precisamos criar uma instância dessa interface. Para criá-la, usamos o objeto RestifyProxyBuilder.

import com.github.ljtfreitas.restify.http.RestifyProxyBuilder;

WhateverApi whateverApi = new RestifyProxyBuilder()
  .target(WhateverApi.class)
    .build();

Também é possível definir a URL base da API no builder, ao invés da anotação @Path no topo da interface.

import com.github.ljtfreitas.restify.http.RestifyProxyBuilder;

WhateverApi whateverApi = new RestifyProxyBuilder()
  .target(WhateverApi.class, "http://whatever.api.com")
    .build();

Por padrão, você pode utilizar apenas String, byte[] ou InputStream como retornos de método, para obter a resposta da requisição. Mas existem diversos plugins que extendem esse comportamento, permitindo utilizar vários objetos diferentes.

No exemplo abaixo, vamos consumir a API do GitHub (que utiliza JSON), deserializando a resposta para um objeto. Podemos utilizar o Jackson para lidar com o JSON, e para usá-lo com o java-restify, precisamos adicionar a dependência java-restify-json-jackson-converter. Com essa dependência no seu classpath, o java-restify irá registrar automaticamente um componente que utiliza o Jackson para serializar/deserializar requisições e respostas no formato JSON.

Usando o Maven:

<dependency>
  <groupId>com.github.ljtfreitas</groupId>
  <artifactId>java-restify-json-jackson-converter</artifactId>
  <version>{version}</version>
</dependency>

Ou o Gradle:

dependencies {
  compile("com.github.ljtfreitas:java-restify-json-jackson-converter:{version}")
}

Primeiro, criamos os objetos representando a API do Github.

@Path("https://api.github.com")
interface GitHub {

  @Path("/repos/{owner}/{repo}/contributors")
  @Get
  public List<Contributor> contributors(
    @PathParameter("owner") String owner,
    @PathParameter("repo") String repo);
}

@JsonIgnoreProperties(ignoreUnknown = true)
class Contributor {

  @JsonProperty
  private String login;

  @JsonProperty
  private int contributions;

  @Override
  public String toString() {
  return "Contributor: [" + login + "] - " + contributions + " contributions.";
  }
}

Agora podemos utilizar o RestifyProxyBuilder para obter uma instância da interface.

GitHub gitHub = new RestifyProxyBuilder()
  .target(GitHub.class)
    .build();

/*
  A chamada do método "contributors" vai realizar um GET para https://api.github.com/repos/ljtfreitas/java-restify/contributors. 
  O "bind" dos argumentos do método com o path é realizado utilizando o nome dos parâmetros.
  A resposta da API do GitHub está no formato application/json; o java-restify irá automaticamente deserializar o JSON de resposta para o tipo de retorno do método
*/

gitHub.contributors("ljtfreitas", "java-restify")
  .forEach(System.out::println);

/*
output:

Contributor: [ljtfreitas] - 127 contributions.
*/