3. متد های HTTP

ـ HTTP تعدادی متد تعریف شده دارد که مشخص می‌کنند چه فعلی روی Resource مورد نظر اعمال میشود.

ـ URL یک جمله است؛ Resource ها اسم های آن و HTTP متد ها فعل های آن هستند.

متد های پر استفاده تر HTTP به قرار زیر اند:

  1. متد GET اطلاعات را از Resource مورد نظر دریافت میکند. مثلا companies/3/employees/اطلاعات مربوط به کارمندان کمپانی 3 را برمی‌گرداند. ( این عمل نباید هیچ تاثیر جانبی دیگری بر سیستم داشته باشد.)
  2. متد POST برای ساخت یک Resource در دیتابیس بکار میرود.(معمولا وقتی یک فرم ارسال میشود.) 
    برای مثال companies/3/employees/ یک کارمند جدید از کمپانی 3 ایجاد می‌کند.
    نکته : این متد non-idempotent است یعنی با تکرار درخواست یک Resource جدید ایجاد می‌کند.
  3. متد PUT درخواستی است که Resource را ویرایش می‌کند و در صورت عدم وجود آنرا می‌سازد. برای مثال companies/3/employees/john/ ـ john را در زیر مجموعه کارکنان کمپانی 3 ویرایش می‌کند و در صورت عدم وجود آنرا میسازد.
    نکته: این متد idempotent است یعنی با تکرار درخواست همان Resource قبلی ویرایش می‌شود.
  4. متد DELETE برای حذف Resource ای که باید از دیتابیس حذف شود بکار می‌رود. برای مثال/companies/3/employees/john/ باعث حذف john از لیست کارمندان کمپانی 3 می‌شود.
    برای اطلاع از متد های دیگر HTTP از ویکی پدیا استفاده کنید.

اصول طراحی RESTful API / بهترین راهکار ها

404 :(

4. کد های وضعیت HTTP Response

وقتی که کلاینت درخواستی از سرور می‌کند باید بتواند به راحتی از وضعیت درخواستش مطلع شود، که درخواستش موفق ،ناموفق و یا غلط بوده است. کد های وضعیت HTTP سریال هایی برای سناریو های مختلفی است که ممکن است روی دهد. سرور همیشه باید کد وضعیت درست را به کلاینت برگرداند. 
در ادامه به معرفی دسته های مختلف کد های وضعیت HTTP می‌پردازیم:

حالت موفق - 2XX
این دسته کد های وضعیت به معنای دریافت درخواست توسط سرور و موفقیت پردازش مورد نظر است:

  • ـ 200 OK: کد استاندارد HTTP برای نمایش موفقیت عملیات های GET,POST ,PUT
  • ـ 201 Created: این کد وضعیت باید بعد از ایجاد شدن یک Resource بازگردانده شود. برای مثال هنگام ساخت با POST
  • ـ 204 No Content: درخواست موفق بوده است ولی هیچ محتوایی برای پاسخ وجود نداشته است. معمولا درخواست DELETE با این کد برمی‌گردد. وقتی درخواست DELETE ارسال میشود ما به صراحت به سرور گفته ایم که یک نمونه را حذف کن و نیازی به بازگشت اطلاعات خاصی نداریم. اگر نمونه مورد نظر وجود نداشته باشد ارور کلاینت رخ داده که در حوزه 4XX قرار میگیرد.

حالت ریدایرکت - 3XX

  • ـ 304 Not Modified: نشان می‌دهد که کلاینت پاسخ را در کش خود دارد و نیازی به ارسال مجدد داده ها به کلاینت نیست.

حالت کلاینت ارور - 4XX

این حالت هنگامی رخ می‌دهد که درخواستی معیوب از سمت کاربر ارسال شود:

  • ـ 400 Bad Request: درخواست توسط سرور انجام نشده است. سرور معنای درخواست کلاینت را متوجه نمی‌شود.
  • ـ 401 Unauthorized: کلاینت اجازه دسترسی به این Resource را ندارد و برای دسترسی باید با اعتبار مشخصی اقدام کند.
  • ـ 403 Forbidden: درخواست درست ارسال شده و کلاینت تایید اعتبار شده است اما به دلیلی به او اجازه دسترسی به Resource داده نمی‌شود. برای مثال کاربران عضو یک وبسایت به فایل های دایرکتوری دسترسی ندارند.
  • ـ 404 Not Found: نشان میدهد در حال حاضر منبعی برای این درخواست موجود نیست.
  • ـ 410 Gone: نشان میدهد مکان Resource مورد نظر جا به جا شده است.

حالت سرور ارور - 5XX

  • ـ 500 Internal Server Error: درخواست درست است ولی سرور در ارائه خواسته کلاینت مشکل دارد. یعنی اروری در حین آماده سازی پاسخ در سرور ایجاد شده است.
  • ـ 503 Service Unavailable: سرور غیر فعال است یا نمی‌تواند درخواست ها را دریافت و پردازش کند. عموما به معنای این است که سرور در حال تعمیر است.

5. قوانین نام گذاری

شما می‌توانید از هر قاعده نام گذاری (naming convention) ای که می‌خواهید پیروی کنید.اما حتما این قاعده را در تمام سطح API رعایت کنید. اگر از JSON برای بدنه درخواست یا پاسخ استفاده می‌کنید سعی کنید که از Camel Case استفاده کنید.

اصول طراحی RESTful API / بهترین راهکار ها

pagination

6. جستجو، مرتب سازی، فیلتر کردن و صفحه بندی

همه این کار ها با کوئری زدن روی دیتاست ها انجام پذیر اند؛ و نیازی به طراحی API مجزا ندارند. کافیست پارامتر هایی به URL خود اضافه کنیم و توسط همان متد GET آنرا درخواست دهیم. بگذارید با چند مثال قضیه را روشن تر کنیم:

  • مرتب سازی: کلاینت می‌خواهد درخواستی برای دریافت لیست مرتب کمپانی ها ارسال کند. پایانه
    GET /companies باید بتواند پارامتر های مختلفی را قبول کند مثل :
    GET /companies?sort=rank_asc که لیست کمپانی ها را بر اساس رنکینگ بصورت صعودی برمی‌گرداند.
  • فیلتر کردن: برای فیلتر کردن دیتاست ها میتوانیم مانند مرتب سازس عمل کنیم مثلا:
    GET /companies?category=banking&location=india بانک هایی که در هند مستقر هستند را برمی‌گرداند.
  • جستجو: مثلا برای جستجو بر اساس نام یک کمپانی :
    GET /companies?search=Digital Mckinsey که اطلاعات کمپانی دیجیتال مکنزی را برمی‌گرداند.
  • صفحه‌بندی: وقتی دیتاست خیلی بزرگ است، آنرا به بخش های کوچک تر تبدیل میکنیم تا بازده سیستم بالاتر رود و پاسخ سریعتر ارسال شود . برای مثال: GET /companies?page=23 کمپانی های بخش 23 را برمی‌گرداند.

نکته: وقتی تعداد پارامتر های ارسالی بالارود و طول URL بیش از حد شود، ممکن است سرور کد 414 URI Too Long بدهد. در این موارد می‌توانید دیتای مورد نظر را در بدنه درخواست POST قرار دهید.

7. نسخه بندی (versioning)

وقتی API شما در حال استفاده است، بهبود دادن آن و تغییر ساختار آن ممکن است در عملکرد نرم افزار هایی که از API شما استفاده می‌کنند مشکل ایجاد کند. این URL یک نمونه مناسب از API است:http://api.yourservice.com/v1/companies/34/employees که عدد ورژن به صراحت در URL ذکر شده است. اگر تغییر اساسی در API شما انجام شد باید ورژن جدیدی از API منتشر کنید. برای مثال از v2 یا v1.x.x استفاده کنید.

تهیه شده توسط مهدی کلهر سایت ویرگول

لاراول
فقط
خوش آمدید!
ایجاد حساب کاربری