RPC: JSON-RPC, XML-RPC e gRPC

Uma chamada pode pedir a execução de um procedimento pelo nome, como consultarPedido, em vez de manipular um recurso identificado na URL. Reconhecer esse modelo ajuda a ler o resultado no lugar certo, que nem sempre é o status HTTP.

Chamada de procedimento remoto

O RPC, chamada de procedimento remoto, organiza a comunicação como a execução de uma operação em outro componente, com parâmetros e um resultado. O contrato define os procedimentos, os parâmetros e as respostas. Em algumas interfaces sobre HTTP, um POST leva o nome da operação no corpo, ou um caminho como /executar?acao=consultarPedido&id=0001 nomeia a operação na URL. O RPC não exige o HTTP nem o POST em todas as implementações.

JSON-RPC

O JSON-RPC 2.0 padroniza as mensagens em JSON. Um pedido tem esta forma:

• {"jsonrpc":"2.0","method":"consultarPedido","params":{"id":"0001"},"id":1}: pede a execução do procedimento consultarPedido com o parâmetro id.

O campo method nomeia o procedimento, o campo params leva os argumentos, e o campo id relaciona a resposta ao pedido. Esse id de correlação não precisa ser o número do pedido de negócio.

A resposta traz result, no sucesso, ou error, na falha, com o mesmo id. Uma notificação é um pedido sem id, que não recebe resposta, e essa situação é diferente de uma chamada que deveria ter retorno e não recebeu.

Os erros padronizados do protocolo usam códigos negativos:

• -32700: o JSON recebido é inválido;
• -32600: a requisição é inválida;
• -32601: o método não existe ou não está disponível;
• -32602: os parâmetros são inválidos;
• -32603: ocorreu um erro interno.

O serviço também define códigos próprios de aplicação. O JSON-RPC pode usar o HTTP, um socket ou outro transporte, e, sobre HTTP, o código 200 não elimina um error no corpo.

XML-RPC

O XML-RPC também chama procedimentos, mas em XML. O pedido tem os elementos methodCall e methodName, a resposta tem methodResponse, e o erro vem em fault. A estrutura é diferente do Envelope do SOAP e não depende de um WSDL, e o método, os parâmetros e o significado do fault vêm do contrato.

gRPC

O gRPC, criado pelo Google, usa o HTTP/2 e mensagens binárias no formato Protocol Buffers. O contrato fica em arquivos .proto, dos quais as ferramentas geram o código do cliente e do servidor. O gRPC aceita chamadas com uma resposta única e fluxos de mensagens em um sentido ou nos dois.

O caminho segue o formato /pacote.Servico/Metodo, e o resultado vem em um status próprio do gRPC, como estes:

• OK: a chamada terminou com sucesso;
• INVALID_ARGUMENT: um argumento é inválido;
• NOT_FOUND: o recurso pedido não existe;
• UNAUTHENTICATED: falta uma credencial válida;
• PERMISSION_DENIED: a credencial não tem permissão;
• UNAVAILABLE: o serviço está indisponível no momento;
• DEADLINE_EXCEEDED: o prazo da chamada acabou antes da resposta.

O conteúdo binário exige ferramentas próprias para a leitura na rede, e o log da aplicação costuma mostrar os campos já decodificados. O gRPC é comum entre serviços internos, mas um programa de estação também pode usá-lo.

Correlação e prazo não tornam a execução única

O id do JSON-RPC relaciona o pedido à resposta, e a especificação não atribui a ele uma proteção contra a execução repetida do procedimento. A repetição de uma chamada de criação segue a política de negócio do serviço, mesmo com o mesmo id.

No gRPC, o deadline limita o tempo que o cliente aceita esperar. O cliente pode receber DEADLINE_EXCEEDED quando o servidor terminou a alteração, mas o retorno não chegou a tempo. Antes de tratar a tentativa como não executada, o status e os efeitos no serviço remoto são conferidos.