Sto creando un'API Web con molte risorse REST. Il mio servizio ha anche alcune attività che dovrebbero essere avviate su richiesta. ad esempio "Inizia a inviare email".
Per ora ho un URL specifico che chiamo "api/v1/start" per avviare l'invio delle e-mail in coda. Ma temo che non sia conforme allo standard REST.
Come posso aggiungere questa funzione al mio servizio RESTfull. E ... REST è una buona opzione per questa domanda o dovrei ignorarla?
For now I do have a specific URL which I call "api/v1/start" in order to start emails queue sending. But I'm afraid that it is not in comply with the REST standard.
REST non si cura di quale ortografia si usa per gli identificatori di risorse. /api/v1/start va bene.
(Tecnicamente, Roy Fielding ha avuto cose molto scortese da dire sulla parte v1 . Si tratta di un problema diverso da quello che stai attualmente chiedendo, comunque)
How can I add this feature on my RESTfull service. And... Is REST a good option for this demand or should I ignore it?
Ci sono due modelli comuni.
Uno è di inviare un messaggio a qualche endpoint, che capisce come interpretare il messaggio e fare la cosa giusta. Questo è analogo a ciò che facciamo quando inviamo un modulo Web in un browser. Il consumatore ha bisogno di sapere quali link seguire e di identificare i campi che deve essere cambiato, quindi il messaggio va ovunque.
L'altro modello è un approccio più dichiarativo, in cui PUT rappresenta una rappresentazione del modo in cui si desidera che la risorsa sia, e il server di origine interpreta la nuova rappresentazione e scopre come farlo.
Esempio: immagina di provare a scrivere un'API REST per un forno da cucina. Il forno è spento e il nostro obiettivo è accenderlo con un'impostazione target di 450F.
Nel primo approccio, vorremmo GET la rappresentazione corrente del forno, e avremmo una forma in entrata, con spunti semantici che spiegano i diversi campi. Inseriremmo 450F nel modulo e lo inoltreremo. Questo sarebbe convertito in una richiesta POST e inviato al server per l'elaborazione.
Nel secondo approccio, vorremmo GET la rappresentazione corrente del forno, con segnali semantici che ci dicono la temperatura corrente. Usando il nostro editor preferito, modificheremmo la nostra copia locale della rappresentazione con la temperatura desiderata di 450F, e quindi PUT la nuova rappresentazione sul server, che quindi capirebbe come raggiungere il nostro stato target desiderato.
What does Roy Fielding Says?
Vedi, per esempio, questo tweet del 2013
a "v1" is a middle finger to your API customers, indicating RPC/HTTP (not REST)
Mi sembra che tu stia parlando di come avviare un lavoro manualmente:
My service also have some tasks which should be started on demand. for instance "Start sending emails".
Bene, inviare e-mail usando questo endpoint api/v1/start è molto vago secondo me. Cosa stai davvero iniziando? Mi sembra che stai iniziando la "versione" (v1), cosa non ha senso. L'URL deve essere auto-esplicativo sulla risorsa. A volte questo è possibile, a volte no.
Nel tuo caso, forse potresti separare le risorse utilizzate dall'applicazione dalle richieste jobs . Quindi, puoi finire con:
POST /api-job/v1/emails/queues/
Scelgo il POST perché non è un PUT, DELETE, GET o PATCH. A volte non hai un buon metodo Http da scegliere, quindi POST agisce come la scelta giusta.
Ho scelto di separare /api/ da /api-jobs/ . Cerca di non mischiare le risorse utilizzate dall'applicazione utente finale con le risorse utilizzate da qualche tipo di back-end o di pianificazione. Questo ti aiuta a controllare ciascuna API in modo indipendente. Puoi sostituire jobs con tasks se preferisci.
Il emails/queues/ è discutibile. Prendo una decisione per scegliere questo tipo di indirizzo, ma queues/emails o solo emails sono anche opzioni. La scelta dipende se stai pensando di avere un altro inizio di code e / o iniziare un'altra attività per le email, come:
POST /api-job/v1/emails/queues/ # start the email sending
DELETE /api-job/v1/emails/queues/ # delete all emails on queue
DELETE /api-job/v1/emails/{email-type} # delete all emails from specific type (that are not on the queue yet)
Questi sono solo esempi.
Le altre risposte sono sulla strada giusta, ma penso che un po 'più specifiche potrebbero aiutare qui. Sulla base di ciò che hai descritto, probabilmente andrei con qualcosa di simile:
api/v1/emails # questo può davvero essere qualsiasi cosa. Scegli qualcosa che sia intuitivo e distinto.
POST crea un nuovo abbonamento email. I parametri possibili sono: indirizzo, filtri. Restituisce un URI api/v1/emails/<subscription-id>
GET restituisce l'elenco degli URI di sottoscrizione correnti.
api/v1/emails/<subscription-id>
GET recupera i dettagli dell'abbonamento
PUT modifica le impostazioni per l'abbonamento
DELETE rimuovi / cancella abbonamento
Leggi altre domande sui tag rest web-applications web-api