Come progettare un'API REST per gestire operazioni non CRUD?

Devi guardare questo parlare di Jim Webber.

When I need to update the state of the subscription, I cannot simply send a POST request to the server, because I don't have direct access to the resources, but I need to call some RPC-style operations to update their properties. Additionally, only and only if I'm changing the state of the subscription to "active", an additional call to an external service is required.

Pensa ai "messaggi"; invia un messaggio al tuo dominio, descrivendo ciò che vuoi che accada. L'effetto collaterale del messaggio è che il tuo modello di dominio cambia effettivamente il suo stato. La "risorsa" è la coda dei messaggi.

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

L'ortografia del nome della risorsa non ha importanza per le macchine; ma le persone tendono a diventare pignoli quando gli identificatori che usi usano la convenzione secondo cui le risorse sono "nomi".

Inoltre, stiamo parlando di una risorsa subordinata a /subscriptions/{subscriptionid} , quindi convenzione (vedi RFC 3986 ) richiede di esprimere tale relazione con un segmento di percorso, anziché utilizzare la parte della query.

Quindi queste ortografie potrebbero essere ragionevoli

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

Se è un flag booleano per attivare / disattivare roba, direi che l'impostazione predefinita è usare JSON:

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

Questo è facilmente estendibile se vuoi supportare più proprietà. Un altro approccio sta dando il suo endpoint:

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

Personalmente, lo userei solo se lo stato di active di questo evento ha / ha proprietà che puoi poi passare / ottenere in JSON, come un ID utente o impostazione.

Se non è un valore booleano ma solo un'azione che è necessario attivare ma non richiede / ha alcun feedback sullo stato per (tranne un immediato 200 OK), utilizzerei un endpoint come questo per attivarlo molto come un RPC :

POST /subscriptions/{subscriptionid}/activate/

In caso di dubbi, leggi questo: link (vedi " Che dire delle azioni che non rientrano nel mondo delle operazioni CRUD? ")

REST non è funzionale. Activate è un verbo e non può essere uno stato, Active è uno stato.

Poiché RESTful non è funzionale, non puoi dire a un servizio RESTful cosa fare, ma puoi aggiungere lavoro per la coda di un servizio.

Vedi questo:

PUT /subscriptionQueue
subscriptionId={subscriptionId}
active=true

Questa richiesta è RESTful e supporta tutti i vantaggi di RESTful (come le prestazioni, l'acido ...)