Idempotent REST APIs

Idempotent REST APIs

در زمینه REST API ها زمانی که چند درخواست یکتا اثر یکسانی دارند مشابه با یک درخواست واحد دارند REST API به idempotent نامیده می شود.

زمانی که REST API ها را طراحی می کنیم باید درک کنیم که مصرف کنندگان API ممکن است اشتباهاتی را مرتکب شوند. مصرف کنندگان ممکن است کد سمت کلاینت را طوری نوشته باشند که چندین درخواست تکراری به سمت سرور ارسال شود.

این درخواست های تکراری ممکن است غیر عمد یا گاهی به عمد باشد (مثلا به دلیل timeout یا مشکلات شبکه)

ما باید api های خود را fault-tolerant کنیم به طوری که درخواست های تکراری سیستم را ناپایدار نکنند.

متد idemotent HTTP متدی است که می تواند چندین بار بدون ورودی متفاوت فراخوانی شود. اگر متد تنها یک بار یا ده بار فراخوانی شود نباید مهم باشد. نتیجه باید همیشه همان باشد.
بحث idemotency لزوما به این معنی است که نتیجه درخواست اجرا شده مستقل از  تعداد دفعات اجرا شده است.
برای مثال در arithmetic اضافه کردن صفر به عدد idemotent است.

اجرای idempotency بهمراه متدهای http

اگر ما اصول rest را در طراحی api های خود دنیال کنیم ما به طور خودکار برای متدهای get, put, delete, head, options, trace دارای idempotent rest api هستیم. فقط api های post هستند که idempotent نیستند.

۱. متد post به صورت idempotent نیست.

۲. متدهای get, put, delete, head, options, trace به صورت idempotent هستند.

بیاید بررسی کنیم متدهای http بالا چطور idempotent هستند در صورتی که post نیست.

متد http post

به طور کلی لزومی وجود ندارد که از post برای ایجاد یک resource جدید روی سرور استفاده کنیم. زمانی که درخواست post یکسانی را N بار فراخوانی میکنیم N تا resource جدید روی سرور ایجاد می شود. لذا POST به صورت idempotent نیست.

متدهای HTTP Get, Head, Options , Trace

متدهای  HTTP Get, Head, Options , Trace هرگز وضعیت resource را روی سرور تغییر نمی دهند. آنها برای بازیابی ارائه منبع یا meta data در آن لحظه هستند. لذا فراخوانی چندین باره درخواست ها هیچ عملیات write ی روی سرور انجام نمی دهد پس اینها idemotent هستند.

درخواست http put

به طور کلی لزومی وجود ندارد که api های put برای برورسانی وضعیت resource استفاده شوند. اگر شما PUT را N مرتبه فراخوانی کنید اولین درخواست resource را آپدیت می کند n-1 درخواست بعدی همان وضعیت resource را دوباره و دوباره بازنویسی می کنند در عمل هیچ چیزی تغییر نمی کند.

لذا put به صورت idemotent است.

درخواست http delete

زمانی که شما N بار درخواست های delete را فراخوانی می کنید اولین درخواست resource را حذف کرده و پاسخ 200 (ok) یا 204 (No content) بر می گرداند. N-1 درخواست دیگر 404 (ٔNot Found) بر می گردانند.

واضح است که پاسخ نسبت به درخواست اول متفاوت است اما تغییری روی وضعیت برای هیچ resource ی در سمت سرور رخ نداده است زیرا resource اصلی قبلا پاک شده است.

لذا Delete  به صورت idemotent است.

 درخواست delete بدون شناسه resource

لطفا به یاد داشته باشید برخی سیستم ها ممکن است DELETE API هایی مثل این داشته باشند:

DELETE /item/last

در مورد بالا فراخوانی N بار عملیات موجب حذف N تا resource خواهد شد لذا delete در این حالت idempotent نیست. در این مورد پیشنهاد خوب این است که api را به صورت post فراخوانی کنیم چون post به صورت idempotent نیست.

POST /item/last

حالا، این به مشخصات HTTP نزدیک‌تر است - از این رو با REST سازگارتر است.

منبع: https://restfulapi.net/idempotent-rest-apis/