HTTP-responskod för bulk-operationer med delvis lyckat resultat

[peter-stranne]

Hej! Hoppas jag ställer frågan på rätt ställe (ny forummedlem här ). Jag undrar om DIGG har någon rekommendation/best practice på HTTP-responskod om man vid en bulk-operation får ett delvis lyckat resultat.

Till exempel om man gör en PUT för att uppdatera 10 sinsemellan oberoende objekt, nio av dessa operationer gick bra, men den tionde misslyckades. Standarden täcker imho inte riktigt detta case, vilket blir en vanligare och vanligare förfrågan från våra API-konsumenter. Idag returnerar vi 207 med en response-body som beskriver vilken eller vilka identifierade objekt som misslyckas, med information om varför dessa misslyckats.

Att skicka 200 eller 204 känns inte rätt då det inte är en fullständigt lyckad operation, men 4XX sänder också fel signal då vi faktiskt har uppdaterat de flersta objekt i requesten. Jag tänker att vi gärna vill implementera detta på ett så tydligt och bra (läs: förväntat) sätt som möjligt, men söker alltså feedback och input. Hoppas frågan var tydlig och att den riktades till rätt ställe.

[peter-stranne]

Försökte redigera inlägget ovan med en referens till rätt del i specen, men det hade visst gått för lång tid, så jag lägger det i en egen kommentar här nedan istället: https://www.dataportal.se/rest-api-profil/api-response

[Jacob]

Tyvärr vet jag inte om DIGG har någon visdom i frågan. Problemet - som du själv skriver - är ju att REST inte handskas med bulk-operationer och att delvis lyckade bulk-operationer bryter rakt av mot RESTs idempotensegenskap. Vill ni hålla det strikt REST så hade ni kanske behövt göra något i stil med att skapa en batch-job endpoint, som svarar 202 med URI till ett jobb som användaren kan GET:a för att komma åt resultatet av batch-jobbet. Annars får man nog helt enkelt vara pragmatisk. 207 är ju icke-standard och mer tänkt för WebDav, men kanske trots allt den bästa kompromissen i just ert fall?

Ett alternativ är att frångå REST för just dessa delar av era API:er och snegla mer mot RPC - då blir allt konceptuellt ett funktionsanrop över POST.

[Jacob]

Liten rättning, klart att bulk-operationer kan vara idempotenta.

[peter-stranne]

Tack för genomtänkt input!

I detta fall är operationerna idempotenta, samma request hade genererat samma resultat även om de skickas igen, så det är imho inte det som är det "största" problemet i just detta scenario. Det är dessutom i detta scenario x antal dataposter som ska läggas till, men de har ingen relation sinsemellan, utan det är för att slippa göra flera hundra i stort sett identiska anrop, vilket hade ökat lasten både för dem och för oss.

Vi är medvetna om att 207 inte är en REST-responskod, men i avsaknad av tydlig best practice här (inte bara från DIGG, utan även på andra sajter så går rekommendationerna isär) så har vi valt denna väg. Givetvis informerar och dokumenterar vi att 207 kan returneras från denna endpoint. Det känns som en renare och enklare lösning istället att behöva loopa "x" antal gånger med full Request + Response-cykel för att göra något som enkelt kan utföras genom att skicka in en array av objekt. Ofta skickas data till oss efter det att datalager eller motsvarande har uppdaterats med någon nattlig körning och då blir det såhär våra kunder vill integrera med oss.

Anledningen till frågan här hos DIGG är att vi gärna vill följa myndighetens rekommendationer i möjligaste mån, men att vi här saknar tydlig vägledning.

Alternativet med 202 Accepted och då skicka med batch-id eller motsv. är helt klart en möjlig väg framåt , och då även mer korrekt enligt RESTful-principerna. Men även den har sina nackdelar imho då den kräver en extra request+responscykel, samt att det är oklart för API-konsumenten när de ska köra sin förfrågan för att kolla resultatet.

Tack igen för input, och andra får såklart också gärna komma med goda tankar och funderingar, vi lär ju inte vara de enda som stött på denna situation tänker jag.

[Jacob]

Jag förstår verkligen kruxet Hoppas på flera intressanta inflikningar!

[DIGG_admin]

@peter-stranne Det sätt ni hanterar scenariot idag får anses som korrekt, dvs att returnera 207 med information om vilka objekt som lyckas och inte lyckas.

Det som man kan ha i åtanke är att vissa klienter som använder vissa API-verktyg, API-gateways och middleware-produkter kan ha problem med att tolka denna statuskod. I detta case skulle man kunna argumentera för att man skulle ha statuskod 200 som response tillsammans med en detaljerad body. Dock behöver detta kikas på utifrån ett behovsperspektiv kopplat till de klienter som använder deras API.

[peter-stranne]

Tack för återkoppling @DIGG_admin . Skönt att vi inte var helt ute och cyklade. Vi är införstådda med baksidorna här, men det kändes för oss som den naturliga lösningen på ett scenario vi ofta stöter på "ute i verkligheten".