Como criar uma API REST para manipular operações não CRUD?

Estou tentando converter um conjunto de serviços baseados em SOAP em uma API RESTful.

Comecei identificando recursos analisando os nomes das operações e obtive o recurso Subscription.

Quando preciso atualizar o estado da assinatura, não posso simplesmente enviar uma POSTsolicitação ao servidor, porque não tenho acesso direto aos recursos, mas preciso chamar algumas operações no estilo RPC para atualizar suas propriedades. Além disso, somente e somente se eu estiver alterando o estado da assinatura para "ativo", será necessária uma chamada adicional para um serviço externo.

Nesses casos, qual é a melhor prática para lidar com operações subjacentes?

A solução que eu encontrei é usar parâmetros de consulta, para que, se eu precisar chamar o serviço de ativação, possa usar algo como:

POST /subscriptions/{subscriptionid}/?activate=true

Considerando que não posso atualizar diretamente meus campos de objeto de inscrição, existe alguma prática recomendada para lidar com esse tipo de conversão?

Atualização 1:

Eu posso colocar no corpo da minha solicitação POST alguns valores, por exemplo "state": "active"

e verificar dentro do meu serviço as operações adequadas a serem acionadas.

Você precisa assistir a essa palestra de Jim Webber.

Quando preciso atualizar o estado da assinatura, não posso simplesmente enviar uma solicitação POST ao servidor, porque não tenho acesso direto aos recursos, mas preciso chamar algumas operações no estilo RPC para atualizar suas propriedades. Além disso, somente e somente se eu estiver alterando o estado da assinatura para "ativo", será necessária uma chamada adicional para um serviço externo.

Pense em "mensagens"; envie uma mensagem para o seu domínio, descrevendo o que você deseja que aconteça. O efeito colateral da mensagem é que seu modelo de domínio realmente altera seu estado. O "recurso" é a fila de mensagens.

POST /subscriptions/{subscriptionid}/?activate=true

A ortografia do nome do recurso não importa para as máquinas; mas as pessoas tendem a ficar exigentes quando os identificadores que você usa quebram da convenção de que recursos são "substantivos".

Além disso, estamos falando de um recurso subordinado /subscriptions/{subscriptionid}, portanto, a convenção (consulte a RFC 3986 ) exige expressar esse relacionamento com um segmento de caminho, em vez de usar a parte da consulta.

Portanto, essas grafias podem ser razoáveis

POST /subscriptions/{subscriptionid}/messages
POST /subscriptions/{subscriptionid}/activations

Se for um sinalizador booleano para ativar / desativar coisas, eu diria que o padrão é usar JSON:

POST /subscriptions/{subscriptionid}/
{
    format: 0,
    subscription: 
    {
        active: false
    }
}

Isso é facilmente estendido se você deseja oferecer suporte a mais propriedades. Outra abordagem está fornecendo seu próprio terminal:

POST /subscriptions/{subscriptionid}/active/
DELETE /subscriptions/{subscriptionid}/active/

Pessoalmente, eu usaria isso apenas se o activeestado desse evento precisar / tiver propriedades que você possa passar / obter no JSON, como um ID de usuário ou configuração.

Se não for um valor booleano, mas apenas uma ação que você precisa disparar, mas não precisa / possui nenhum feedback de status (exceto um OK imediato 200), eu usaria um ponto de extremidade como esse para acioná-lo como um RPC:

POST /subscriptions/{subscriptionid}/activate/

Em caso de dúvida, leia o seguinte: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful (consulte "E as ações que não se encaixam no mundo das operações CRUD? ")

O REST não é funcional. Activateé um verbo e não pode ser um estado, Activeé um estado.

Como o RESTful não é funcional, você não pode dizer ao serviço RESTful o que fazer, mas pode adicionar trabalho para a fila de um serviço.

Veja isso:

PUT /subscriptionQueue
subscriptionId={subscriptionId}
active=true

Esta solicitação é RESTful e suporta todos os benefícios do RESTful (como desempenho, ácido ...)