A partir do Java EE 7, com o lançamento do JAX-RS 2.0 na especificação JSR-339 construir APIs Rest no Java EE se tornou muito mais simples, onde, com poucas anotações é possível disponibilizar serviços Rest.

A biblioteca responsável pela criação de webservices com Rest no Java EE é jax-rs, que é representado pela dependência javax.ws.rs-api:
pom.xml

<dependency>
    <groupId>javax.ws.rs</groupId>
    <artifactId>javax.ws.rs-api</artifactId>
    <version>2.0</version>
    <scope>provided</scope>
</dependency>

Nos servidores de aplicações, com suporte full ao Java EE 7 a dependência do jax-rs já é provida, por isso, a dependência foi declarada como escopo de provided no exemplo acima.

A única “configuração” necessária para criar as APIs no Java EE é estender a classe Application, que ativa o suporte ao JAX-RS e definir um endereço padrão na anotação @ApplicationPath, que será o caminho root dos serviços, ou seja, todos os serviços criados dentro da aplicação vão iniciar pelo path “/api”.

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("api")
public class RestApplication extends Application {
}

Essas implementações podem ser feitas na própria classe que disponibiliza o serviço, porém, por fatores de organização gosto de deixar em uma classe separada essas configurações.

Após o suporte ao JAX-RS ativado e o path root do serviço definido estamos prontos para começar a criar nossos serviços, que são métodos de uma determinada classe com anotações que os transformam em serviços externo.

São necessárias basicamente três anotações, a primeira para definir qual método do HTTP será utilizado no serviços @GET, @POST, @PUT ou @DELETE, depois o Path que irá invocar o serviço e por último a anotação para definir qual o formato que será gerado, exemplo @Produces MediaType.APPLICATION_JSON, que significa que será produzido um JSON como resultado, essas configurações são demonstrada na classe Resouce abaixo:

@Path("rest")
public class Resource {

    @GET
    @Path("hello")
    @Produces(MediaType.APPLICATION_JSON)
    public String hello() {
        return "Hello";
    }
}

O resultado dessa implementação é um serviço que retorna a string Hello no formato JSON via método Get do HTTP, que pode ser chamada pelo endereço: http://localhost:8080/api/rest/hello.

Agora, em um exemplo completo de uma API, será criado a classe PessoaResource que é responsável por criar 3 serviços: listar, buscar por código e salvar.

import javax.inject.Inject;
import javax.inject.Named;
import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import java.util.List;

@Named
@Path("pessoa")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class PessoaResource {

    @Inject
    private PessoaService pessoaService;

    @GET
    @Path("listar")
    public List<Pessoa> listarPessoas() {
        return pessoaService.findAll();
    }

    @GET
    @Path("buscar/{codigo}")
    public Pessoa listarPessoas(@PathParam("codigo") Long codigo) {
        return pessoaService.findById(codigo);
    }

    @POST
    @Path("cadastrar")
    public Response salvar(Pessoa pessoa) {
       pessoaService.save(pessoa);
       return Response.ok().build();
    }
}

• @Named: Anotação do CDI para marcar classe no contexto gerenciado;
• @Path: Declara qual vai ser o endereço desse serviço, no caso /pessoa;
• @Produces: Configura que toda informação produzida será no formato passado por parâmetro, no caso JSON
• @Consumes: Mesmo comportamento do produces, mas em relação aos dados consumidos

As anotações @Produces e @Consumes podem ser anotados tanto na classe, como no método, então caso declarado na classe a configuração vale para todos os serviços e caso no método, aplica apenas no serviço anotado.

A classe PessoaResource disponibiliza os três endereços:

• GET: http://localhost:8080/api/pessoa/listar
• GET: http://localhost:8080/ws/pessoa/buscar/1
• POST: http://localhost:8080/ws/pessoa/cadastrar

O Exemplo completo está disponível no github