Modelagem dos serviços
Nesta seção falaremos da modelagem e desenvolvimento dos serviços utilizando REST. Para ilustrar bem os cenários abordados, trabalharemos em cima de um problema proposto: um processo de leilão do Mercado Livre.
Apresentação do problema
O problema que buscaremos resolver envolve serviços referentes a um processo de leilão do Mercado Livre. Num leilão típico, um usuário cadastrado no site coloca para venda um produto (novo ou usado), definindo um valor para o lance inicial e então aguarda pelas ofertas de compra por parte de outros usuários interessados no produto.
Após receber algumas ofertas pelo produto, em um determinado momento o vendedor decide aceitar a melhor oferta recebida, e então vende o produto para o comprador que fez esta oferta, encerrando neste momento o leilão. Em seguida à venda, ocorrem os trâmites de pagamento e entrega do produto (que não trataremos aqui) e no final, vendedor e comprador avaliam um ao outro, o que é essencial para os usuários sentirem maior segurança ao realizar negociações futuras deste gênero.
Na modelagem desta aplicação, quatro entidades serão utilizadas: Usuário, Item, Oferta e Avaliação.
Modelagem com Recursos
O ponto de partida do desenvolvimento com REST é definir quais são os recursos envolvidos, com base nos requisitos do sistema e nos serviços que se deseja oferecer. No nosso exemplo, esta etapa não é complexa. Os recursos que manipularemos são: Usuario, Item, Oferta e Avaliacao.
Embora esta identificação tenha sido trivial no domínio que definimos, em alguns casos este processo pode ser um dos mais complexos na modelagem da aplicação. De uma maneira geral, quanto mais a aplicação se aproxima de um CRUD, mais fácil é a identificação dos recursos.
Para este processo de leilão, os serviços que disponibilizaremos serão os da Tabela 1:
|
Serviço |
Descrição |
|
Anunciar item |
Permite que um usuário coloque um produto à venda. |
|
Buscar itens do vendedor |
Pesquisa os itens à venda de um vendedor. |
|
Cadastrar usuário |
Realiza o cadastro de um novo usuário no site. |
|
Realizar oferta |
Permite que um comprador faça uma oferta por um produto. |
|
Retirar oferta |
Permite a remoção de uma oferta por parte do comprador. |
|
Buscar ofertas do item |
Pesquisa por todas as ofertas feitas sobre um produto. |
|
Buscar melhor oferta |
Busca a melhor oferta feita até o momento sobre um produto. |
|
Aceitar melhor oferta |
Permite que um vendedor aceite a melhor oferta feita sobre o seu produto, e com isso encerre o leilão do mesmo. |
|
Avaliar usuário |
Realiza a avaliação de um usuário por parte de outro usuário, após o término do processo de compra. |
|
Buscar avaliações do usuário |
Pesquisa por todas as avaliações recebidas por um usuário. |
Tabela 1. Serviços oferecidos para interação com o processo de leilão.
Protocolo de comunicação REST
Tendo definido os recursos e os serviços que precisamos oferecer, é necessário definir as manipulações possíveis sobre os recursos existentes. Esta etapa é a tradução de operações de negócio em interações diretas sobre usuários, ítens, ofertas e avaliações. Esta tradução feita explorando os recursos do HTTP nos levará a um conjunto de URIs que a aplicação oferece para os clientes.
Para elaborar um bom protocolo de comunicação REST, devemos pensar em algumas questões importantes, como estas:
- Quais são os recursos?
- Quais são as URIs?
- Quais são os formatos manipulados?
- Que métodos HTTP são aceitos em cada URI?
- Que status HTTP deve ser retornado em cada situação?
- Que cabeçalhos HTTP são relevantes em cada situação?
A definição das URIs e dos métodos HTTP aceitos é primordial para um protocolo REST com clareza e de fácil utilização e extensão. Ao ler as URIs já devemos ser capazes de entender quais são os recursos presentes nas mesmas, e o casamento delas com os métodos HTTP deve ser intuitivo.
A Tabela 2 descreve todas as URIs disponíveis na aplicação e quais métodos HTTP podem ser invocados em cada uma delas. Além disso, são especificados os recursos manipulados por cada requisição e o efeito que uma determinada chamada exerce sobre os recursos existentes.
|
URI |
Método |
Formato |
Efeito |
|
/item/{id} |
GET |
Item |
Busca um item. |
|
PUT |
Item |
Atualiza um item. | |
|
/item/{id}/ofertas |
GET |
Coleção de ofertas |
Busca ofertas feitas sobre um item. |
|
POST |
Oferta |
Adiciona oferta a um item. | |
|
/oferta/{id} |
GET |
Oferta |
Busca uma oferta. |
|
PUT |
Oferta |
Atualiza uma oferta. | |
|
DELETE |
- |
Remove uma oferta. | |
|
/usuario |
POST |
Usuario |
Cadastra um usuário. |
|
/usuario/{id} |
GET |
Usuario |
Busca um usuário. |
|
PUT |
Usuario |
Atualiza um usuário. | |
|
/usuario/{id}/avaliacoes |
GET |
Coleção de avaliações |
Busca as avaliações recebidas por um usuário. |
|
/usuario/{id}/itens |
GET |
Coleção de ítens |
Busca os ítens anunciados por um determinado usuário. |
|
POST |
Item |
Usuário coloca novo item à venda. | |
|
/avaliacao/{id} |
GET |
Avaliação |
Busca uma determinada avaliação. |
|
/avaliacao/de/{id}/para/{id} |
POST |
Avaliação |
Realização da avaliação de um usuário sobre outro. |
|
/services |
GET |
Coleção de URIs |
Consulta URIs e métodos HTTP disponíveis para acesso. |