Codice di stato HTTP per "Still Processing"

Sto creando un'API RESTful che supporti l'accodamento di attività di lunga durata per l'eventuale gestione.

Il flusso di lavoro tipico per questa API sarebbe:

1. L'utente compila il modulo
2. Il client pubblica i dati nell'API
3. L'API restituisce 202 Accettato
4. Il client reindirizza l'utente a un URL univoco per quella richiesta ( /results/{request_id})
5. ~ Fine ~
6. Il cliente visita nuovamente l'URL e vede i risultati su quella pagina.

Il mio problema è al passaggio 6. Ogni volta che un utente visita la pagina, invio una richiesta alla mia API ( GET /api/results/{request_id}). Idealmente, l'attività sarebbe stata completata ormai, e restituirei 200 OK con i risultati della loro attività.

Ma gli utenti sono invadenti e mi aspetto molti aggiornamenti troppo zelanti, quando il risultato non è ancora finito l'elaborazione.

Qual è la mia migliore opzione per un codice di stato per indicare che:

• questa richiesta esiste,
• non è ancora finito,
• ma non ha fallito.

Non mi aspetto che un unico codice comunichi tutto ciò, ma mi piacerebbe qualcosa che mi permetta di passare i metadati invece che il client si aspetti il ​​contenuto.

Potrebbe avere senso restituire un 202, dal momento che qui non avrebbe altro significato: è una GETrichiesta, quindi nulla può essere "accettato". Sarebbe una scelta ragionevole?

L'ovvia alternativa a tutto ciò - che funziona, ma sconfigge uno scopo dei codici di stato - sarebbe quella di includere sempre i metadati:

200 OK

{
    status: "complete",
    data: {
        foo: "123"
    }
}

...o...

200 OK

{
    status: "pending"
}

Poi sul lato client, vorrei (sigh) switchsu response.data.statusper determinare se la richiesta è stata completata.

È questo che dovrei fare? O c'è un'alternativa migliore? Questo mi sembra proprio Web 1.0.

HTTP 202 accettato (HTTP / 1.1)

Stai cercando lo HTTP 202 Acceptedstato. Vedi RFC 2616 :

La richiesta è stata accettata per l'elaborazione, ma l'elaborazione non è stata completata.

Elaborazione HTTP 102 (WebDAV)

RFC 2518 suggerisce di utilizzare HTTP 102 Processing:

Il codice di stato 102 (Elaborazione) è una risposta temporanea utilizzata per informare il client che il server ha accettato la richiesta completa, ma non l'ha ancora completata.

ma ha un avvertimento:

Il server DEVE inviare una risposta finale dopo il completamento della richiesta.

Non sono sicuro di come interpretare l'ultima frase. Il server dovrebbe evitare di inviare qualcosa durante l'elaborazione e rispondere solo dopo il completamento? O forza solo a terminare la risposta solo al termine dell'elaborazione? Questo potrebbe essere utile se vuoi segnalare i progressi. Invia HTTP 102 e scarica la risposta byte per byte (o riga per riga).

Ad esempio, per un processo lungo ma lineare, puoi inviare cento punti, arrossendo dopo ogni carattere. Se il lato client (come un'applicazione JavaScript) sa che dovrebbe aspettarsi esattamente 100 caratteri, può abbinarlo a una barra di avanzamento da mostrare all'utente.

Un altro esempio riguarda un processo che consiste in diversi passaggi non lineari. Dopo ogni passaggio, è possibile svuotare un messaggio di registro che verrà eventualmente visualizzato all'utente, in modo che l'utente finale possa sapere come sta andando il processo.

Problemi con lavaggio progressivo

Nota che mentre questa tecnica ha i suoi meriti, non la consiglierei . Uno dei motivi è che forza la connessione a rimanere aperta, il che potrebbe nuocere in termini di disponibilità del servizio e non si adatta bene.

Un approccio migliore è rispondere HTTP 202 Acceptede consentire all'utente di ricontattarti in un secondo momento per determinare se l'elaborazione è terminata (ad esempio chiamando ripetutamente un determinato URI come quello /process/resultche risponderebbe con HTTP 404 non trovato o HTTP 409 conflitto fino al processo termina e il risultato è pronto) oppure avvisa l'utente al termine dell'elaborazione se è possibile richiamare il client, ad esempio tramite un servizio di coda messaggi ( esempio ) o WebSocket.

Esempio pratico

Immagina un servizio web che converte i video. Il punto di ingresso è:

POST /video/convert

che prende un file video dalla richiesta HTTP e fa un po 'di magia con esso. Immaginiamo che la magia richieda un utilizzo intensivo della CPU, quindi non può essere eseguita in tempo reale durante il trasferimento della richiesta. Ciò significa che una volta trasferito il file, il server risponderà con un HTTP 202 Acceptedcontenuto JSON, il che significa "Sì, ho il tuo video e ci sto lavorando; sarà pronto da qualche parte in futuro e sarà disponibile tramite l'ID 123. "

Il client ha la possibilità di abbonarsi a una coda di messaggi per ricevere una notifica al termine dell'elaborazione. Al termine, il client può scaricare il video elaborato andando a:

GET /video/download/123

che porta a un HTTP 200.

Cosa succede se il client richiede questo URI prima di ricevere la notifica? Bene, il server risponderà HTTP 404poiché, in effetti, il video non esiste ancora. Al momento potrebbe essere preparato. Potrebbe non essere mai stato richiesto. Potrebbe esistere qualche tempo nel passato ed essere rimosso in seguito. Tutto ciò che conta è che il video risultante non è disponibile.

Ora, cosa succede se al cliente interessa non solo il video finale, ma anche i progressi (che sarebbe ancora più importante se non ci fosse un servizio di coda messaggi o un meccanismo simile)?

In questo caso, è possibile utilizzare un altro endpoint:

GET /video/status/123

che darebbe una risposta simile a questa:

HTTP 200
{
    "id": 123,
    "status": "queued",
    "priority": 2,
    "progress-percent": 0,
    "submitted-utc-time": "2016-04-19T13:59:22"
}

Eseguendo la richiesta più e più volte mostrerà l'avanzamento fino a quando non sarà:

HTTP 200
{
    "id": 123,
    "status": "done",
    "progress-percent": 100,
    "submitted-utc-time": "2016-04-19T13:59:22"
}

È fondamentale fare la differenza tra questi tre tipi di richieste:

• POST /video/convertmette in coda un'attività. Dovrebbe essere chiamato solo una volta: richiamarlo avrebbe messo in coda un'attività aggiuntiva.
• GET /video/download/123riguarda il risultato dell'operazione: la risorsa è il video. L'elaborazione - questo è ciò che è accaduto sotto il cofano per preparare il risultato effettivo prima della richiesta e indipendentemente dalla richiesta - è irrilevante qui. Può essere chiamato una o più volte.
• GET /video/status/123riguarda il trattamento in sé . Non mette in coda nulla. Non importa del video risultante. La risorsa è l'elaborazione stessa. Può essere chiamato una o più volte.

L'ovvia alternativa a tutto ciò - che funziona, ma sconfigge uno scopo dei codici di stato - sarebbe quella di includere sempre i metadati:

Questo è il modo corretto di procedere. Lo stato in cui si trovano le risorse rispetto al registro specifico del dominio (noto anche come logica aziendale) dipende dal tipo di contenuto della rappresentazione della risorsa.

Ci sono due concetti di differenza che si fondono qui che sono in realtà diversi. Uno è lo stato del trasferimento di stato tra client e server di una risorsa, e l'altro è lo stato della risorsa stessa in qualunque contesto il dominio aziendale comprenda i diversi stati di quella risorsa. Quest'ultimo non ha nulla a che fare con i codici di stato HTTP.

Ricorda che i codici di stato HTTP corrispondono al trasferimento di stato tra client e server della risorsa trattata, indipendentemente da qualsiasi dettaglio di quella risorsa. Quando sei GETuna risorsa, il tuo client chiede al server una rappresentazione di una risorsa nello stato attuale in cui si trova. Che potrebbe essere l'immagine di un uccello, potrebbe essere un documento di Word, potrebbe essere l'attuale temperatura esterna. Al protocollo HTTP non importa. Il codice di stato HTTP corrisponde al risultato di quella richiesta. Ha fatto il POSTdal client al server trasferire una risorsa al server, dove il server poi ha dato un URL che il cliente può visualizzare? Sì? Quindi questa è una 201 Createdrisposta.

La risorsa potrebbe essere una prenotazione di una compagnia aerea che è attualmente nello stato "da rivedere". Oppure potrebbe essere l'ordine di acquisto del prodotto che si trova nello stato "approvato". Tali stati sono specifici del dominio e non riguardano il protocollo HTTP. Il protocollo HTTP si occupa del trasferimento di risorse tra client e server.

Il punto di REST e HTTP è che i protocolli non si occupano dei dettagli delle risorse. Questo è di proposito, non si occupa dei problemi specifici del dominio in modo che possa essere utilizzato senza dover sapere nulla sui problemi specifici del dominio. Non reinterpretare cosa significano i codici di stato HTTP in ogni diverso contesto (un sistema di prenotazione di una compagnia aerea, un sistema di elaborazione di immagini, un sistema di sicurezza video ecc.).

Le cose specifiche del dominio sono per il client e il server per capire tra loro in base Content Typealla risorsa. Il protocollo HTTP è indipendente da questo.

Per quanto riguarda il modo in cui il client scopre che la risorsa richiesta è cambiata di stato, il polling è la soluzione migliore in quanto mantiene il controllo sul client e non assume una connessione ininterrotta. Soprattutto se saranno potenzialmente ore prima che lo stato cambi. Anche se hai detto all'inferno con REST, manterrai la connessione aperta, mantenendola aperta per ore e supponendo che nulla vada storto sarebbe una cattiva idea. Che cosa succede se l'utente chiude il client o la rete si spegne. Se la granularità è di ore, il client può semplicemente richiedere lo stato ogni pochi minuti fino a quando la richiesta passa da "in sospeso" a "completato".

Spero che aiuti a chiarire le cose

Ho trovato ragionevoli i suggerimenti di questo blog: REST e lavori di lunga durata .

Riassumere:

1. Il server restituisce il codice "202 Accettato" con l'intestazione "Posizione" impostata su un URI affinché il client possa controllare lo stato, ad es. "/ Coda / 12345".
2. Fino al termine dell'elaborazione, il server risponde alle richieste di stato con "200 OK" e alcuni dati di risposta che mostrano lo stato del lavoro.
3. Al termine dell'elaborazione, il server risponde alle query di stato con "303 Visualizza altro" e "Posizione" contenente URI al risultato finale.

Il codice di stato HTTP per la risorsa non ancora disponibile suggerisce di restituire una risposta al conflitto 409, piuttosto che una risposta 404, nel caso in cui una risorsa non esiste perché è nel mezzo della generazione.

Dalle specifiche w3 :

10.4.10 409 Conflitto

Impossibile completare la richiesta a causa di un conflitto con lo stato corrente della risorsa. Questo codice è consentito solo nelle situazioni in cui è previsto che l'utente possa essere in grado di risolvere il conflitto e inviare nuovamente la richiesta. Il corpo di risposta DOVREBBE includere abbastanza

informazioni affinché l'utente possa riconoscere l'origine del conflitto. Idealmente, l'entità di risposta dovrebbe includere informazioni sufficienti per l'utente o l'agente utente per risolvere il problema; tuttavia, ciò potrebbe non essere possibile e non è necessario.

È più probabile che si verifichino conflitti in risposta a una richiesta PUT. Ad esempio, se si utilizzava il controllo delle versioni e l'entità in fase di PUT includeva modifiche a una risorsa in conflitto con quelle fatte da una richiesta precedente (di terze parti), il server potrebbe utilizzare la risposta 409 per indicare che non è possibile completare la richiesta . In questo caso, l'entità della risposta conterrebbe probabilmente un elenco delle differenze tra le due versioni in un formato definito dal Content-Type di risposta.

Questo è leggermente imbarazzante, poiché il codice 409 è "consentito solo nelle situazioni in cui si prevede che l'utente possa essere in grado di risolvere il conflitto e inviare nuovamente la richiesta". Suggerisco che il corpo della risposta includa un messaggio (possibilmente in un formato di risposta corrispondente al resto dell'API) come "Questa risorsa è attualmente in fase di generazione. È stata avviata alle [ORA] e si stima che si completi al [ORA]. riprovare più tardi."

Si noti che suggerirei l'approccio 409 solo se è altamente probabile che l'utente che richiede la risorsa sia anche l'utente che ha avviato la generazione di tale risorsa. Gli utenti non coinvolti nella generazione della risorsa troverebbero un errore 404 meno confuso.