برنامه نویس شی گرا

مبتنی بر REST فکر کنید

اگر این مقاله را میخوانید، احتمالا در مورد طراحی رابطهای برنامه نویسی حساس هستید و دوست دارید از اصول طراحی اثبات شده در طراحی Web API خود استفاده کنید.

چون REST بیشتر استایل معماری نرم افزار می باشد تا استاندارد موکد، بنابراین انعطاف پذیری خوبی دارد. بدلیل همین آزادی ساختار و انعطاف پذیری، فرصت مناسبی برای طراحی بهترین راهبردها وجود دارد.

این مقاله مجموعه ای از راهکارهای طراحی است که هنگام همکاری با چندین تیم طراحی API در شرکت Apigee توسعه داده ایم.

ما نقطه نظر خود را در طراحی API - عملگرا - مینامیم زیرا این راهکار، موفقیت برنامه نویس را مهمتر از هر اصل دیگری قرار میدهد. برنامه نویس مشتری API می باشد. موفقیت  طراحی API با این سنجیده میشود که برنامه نویسان چقدر سریع میتوانند از ‌API شما استفاده موفقیت آمیز داشته باشند.

ما طرفدار افراطی رست نیستیم !

طراحی API از منظر بیرون به درون بررسی خواهد شد. یعنی با این سوال شروع میکنیم: هدف ما از طراحی API چیست؟
وظیفه API این است که تاجایی که ممکن است برای برنامه نویس مفید باشد. طراح API باید از دید یک برنامه نویس استفاده کننده از سرویس به آن نگاه کند.

اسم خوب است؛ فعل بد

اصل اول طراحی عملگرا مبتنی بر رست (Restful) : همه چیز را ساده نگه دارید.

آدرس پایه خود را ساده و واضح نگه دارید

آدرس (URL) پایه مهمترین بخش در کارایی API شماست. یک آدرس پایه ساده و واضح استفاده از API شما را آسان میکند. کارایی بدین معناست که چیزی بدون استفاده از مستندات قابل استفاده باشد. برای مثال در مورد دستگیره یک در، بدون نیاز به مستندات شما میدانید که به کدام طرف باز و به کدام طرف بسته میشود. یک تست کلیدی در مورد طرح یک Web API این است که حتما باید فقط دو آدرس پایه برای هر منبع وجود داشته باشد. اجازه دهید یک API در مورد یک شی یا منبع ساده - یک سگ - را مدل سازی کنیم و یک API برای آن ایجاد نماییم. آدرس اول برای یک مجموعه است و دومی برای یک عنصر خاص در مجموعه.

/dogs
/dogs/1234

افعال را از آدرسهای پایه خود خارج کنید

بسیاری از Web API ها از یک رهیافت مبتنی بر متد (method-driven) برای طراحی آدرسها استفاده میکنند. این آدرسهای مبتنی بر متد، گاهی در ابتدا و گاهی در انتها شامل افعال میشوند. برای هر منبع که شما مدل میکنید، مثل سگ مثال بالا، نمیتوانید همیشه یک آیتم تکی را در نظر بگیرید. همیشه منابع مرتبط و جذابی در مورد آن وجود دارند؛ مثل صاحب سگ، غذا، غلاده، نژاد و ... در مورد فرخوانی متدهایی که برای دنیای کوچک یک سگ نیاز است فکر کنید. خیلی سریع شما لیست بلند بالایی از متدهایی خواهید داشت که از الگوی واحدی پیروی نمیکنند و برای توسعه دهندگان استفاده از API شما سخت خواهد بود.

از افعال HTTP برای اعمال روی مجموعه ها و عناصر استفاده کنید

برای منبع سگ، ما دو آدرس پایه که از اسمها و برچسبها استفاده میکنند داریم و میتوانیم روی آنها با افعال HTTP عمل کنیم. افعال HTTP عبارتند از : POST, GET, PUT و DELETE. میتوانیم این افعال را معادل اصطلاح CRUD در دنیای پایگاه داده بدانیم (CREATE-READ-UPDATE-DELETE). با دو منبع خود (/dogs و /dogs/1234) و چهار فعل HTTP، به مجموعه از قابلیتها میرسیم که برای برنامه نویسان آشناست. در زیر چارتی وجود دارد که نحوه استفاده از آنها را نشان میدهد. نکته در این است که احتمالا برنامه نویسان برای فهمیدن نحوه عملکرد API ما نیازی به این چارت نخواهند داشت. آنها میتوانند بدون استفاده از مستندات، API  را آزمایش کنند و آن را یاد بگیرند. بطور خلاصه:

• از دو آدرس پایه برای هر منبع استفاده کنید.
• از افعال در آدرسهای پایه خود استفاده نکیند.
• از افعال HTTP برای اعمال روی مجموعه ها و عناصر استفاده کنید.

اسامی جمع و اسامی واقعی

در ادامه نحوه انتخاب اسم برای منابع را شرح میدهیم. آیا باید از اسامی مفرد یا جمع برای منابع خود استفاده کنید؟  میدانید که API های محبوب از هردو استفاده میکنند. با هم به چند مثال نگاه میکنم :

• Foursquare: /cheins
• GroupOn: /deals
• Zappos: /Product

با توجه به اینکه اولین کاری که ممکن است افراد با یک RESTful API انجام دهند اجرای یک GET است، بنابراین ما فکر میکنیم استفاده از اسامی جمع بهتر می باشد. اما مهمتر از آن این است که از یک مدل مخلوط که برخی آدرسهایتان مفرد و برخی جمع باشند استفاده نکنید. یکنواخت بود به برنامه نویسان اجازه میدهد که فراخوانی های متد را پیش بینی کنند و بتوانند براحتی با API شما کار کنند.

اسامی واقعی از اسامی مجازی بهتر هستند

رسیدن به مجردسازی محض هدف برخی از معماران API می باشد. هر چند این مجازی سازی همیشه برای برنامه نویسان قابل فهم نیست. بعنوان مثال یک API که به محتوا از طریق فرمهای مختلف مثل وبلاگ، ویدیو، اخبار و یا غیره دسترسی دارد. اگر این API همه چیز را با بیشترین درجه مجردسازی مدل کند - مثل /items یا /assets - فرصت این که برنامه نویسان بتوانند تصویر واضحی از نحوه کار API را داشته باشند از دست میدهد. این بسیار قابل فهمتر و مفید تر است که منابع تحت عناوینی مانند وبلاگها، ویدیوها  و اخبار لیست شوند. میزان مجردسازی به سناریوی شما بستگی دارد. شما باید تعداد قابل مدیریتی از منابع داشته باشید. هدف خود را استفاده از نامهای واقعی قرار دهید و سعی کنید تعداد منابع را بین 12 تا 24 حفظ کنید. در مجموع : یک API کاربردی از اسامی جمع به جای اسامی مفرد و از اسامی واقعی به جای مجرد استفاده میکند.

وابستگی ها را کم کنید - پیچیدگی را پشت علامت ؟ پنهان کنید.

در این بخش وابستگیهای بین منابع و پارمترهایی نظیر وضعیتها و صفات را در نظر خواهیم گرفت.

وابستگی ها

منابع همیشه به منابع دیگر وابستگی دارند. راه ساده برای نمایش این وابستگی ها در یک Web API چیست؟ اجازه دهید دوباره به API ای که در بالا مدل کردیم نگاه کنیم. ما از افعال HTTP برای اعمال روی منابع استفاده میکنیم. سگهای ما حتما صاحبانی دارند. برای اینکه تمام سگهایی که به یک فرد خاص تعلق دارند را لیست کنیم، یا یک سگ جدید برای آن شخص ایجاد کنیم از یک GET و POST استفاده خواهیم کرد :

GET /owners/5678/dogs
POST /owners/5678/dogs

حالا، روابط میتوانند پیچیده تر شوند. صاحبان سگها میتوانند با دامپزشکان و آنها با سگها که آنها نیز با غذا ها ارتباط دارند، مرتبط هستند. این که از یک رشته بلند استفاده کنیم و آدرسی با عمق 5 یا 6 مرحله داشته باشیم معمول نیست. به یاد داشته باشید وقتی شما کلید اولیه را برای یک مرحله در اختیار دارید دیگر نیازی به مراحل بالاتر ندارید. به عبارت دیگر در بسیاری از موارد به عمقی بیشتر از /resource/identifier/resource نیاز ندارید.

پیچیدگی را پشت علامت سوال پنهان کنید

اکثر API ها پیچیدگیهایی در پس آدرس پایه یک منبع دارند. این پیچیدیگها میتواند شامل وضعیتهای مختلف که باید بروز، جستجو یا حذف شوند باشند. برای برنامه نویسان استفاده از آدرس پایه را با اضافه کردن وضعیتها و صفات اختیاری به انتهای علامت سوال HTTP ساده کنید. برای مثال لیست تمام سگهای قرمزی که در پارک در حال دویدن هستند :

GET /dogs?color=red&state=running&location=park

خلاصه : API خود را با ساده کردن روابط بین منابع و جاسازی پارمترها و پیچیدگی های دیگر در پشت علامت سوال HTTP ساده تر کنید.

مدیریت خطاها

بسیاری از برنامه نویسان از جمله خود من، دوست ندارند در مورد استثناها و خطاهایی که در برنامه رخ میدهد فکر کنند. اما مدیریت خطاها یک قطعه مهم از پازل نرم افزار و بخصوص یک API می باشد.

چرا مدیریت خطا برای طراحان API مهم است؟

از نگاه برنامه نویسی که از API شما استفاده میکند، هر چیزی در پس API شما یک جعبه سیاه است. بنابراین خطاها یک ابزار کلیدی برای فراهم آوردن محتوا و وضوح در نحوه استفاده از API شما هستند. در ابتدا توسعه دهندگان یاد میگیرند از طریق خطاها یاد بگیرند. مفهوم - ابتدا تست - در متدولوژی extreme و اخیرا مدلهای توسعه مبتنی بر تست الگوهای جامعی در این مورد ارایه میدهند. در ضمن علاوه بر استفاده از خطاها در هنگام توسعه برنامه ها، برنامه نویسان به خروجی این خطاها در هنگام اشکالزدایی و حل مشکلات برنامه هایی که نوشته اند نیاز دارند.

در مدل عملگرا چگونه در مورد خطاها فکر کنیم؟

اجازه دهید راهبرد سه API برتر را در این مورد مرور کنیم :

Facebook:
HTTP Status Code : 200
{"type":"OauthExecption","message":"(#803) Some of the aliases you requested do not exist: foo.bar"}
Twilio:
HTTP Status Code : 401
{"status":"401","message":"Authenticate","code":20003,"more info":"http://www.twilio.com/docs/errors/20003"}
SimpleGeo
HTTP Status Code : 200
{"code":401,"message":"Authentication Required"}

Facebook

مهم نیست که از در یک درخواست از Facebook چه اتفاقی بیفتد، شما همیشه یک کد وضعیت 200 به این معنا که همه چیز درست است دریافت میکنید. اکثر پیغامهای خطا هم در داخل پاسخ HTTP جاسازی میشوند. در مثال بالا آنها یک خطا با شماره #803 نمایش داده اند ولی هیچ اطلاع اضافه ای که این خطا چیست و چگونه باید با آن برخورد کرد ناده اند.

Twilio

دربرخود با خطاها Twilio کار بزرگی انجام داده است و علاوه بر نمایش خطا با استفاده از کد وضعیت HTTP، یک لینک برای مستندات خطا ارایه کرده است. کامنتهای افراد و بحث های پیرامون این مستندات در صفحه مربوطه یک بدنه از اطلاعات مفید در مورد این خطاها را تشکیل میدهند.

SimpleGeo

SimpleGeo کدهای خطا را نمایش میدهد ولی هیچ ارزش اضافه ای ندارد.

چند راهکار خوب

از کدهای وضعیت HTTP استفاده کنید

از کدهای HTTP استفاده کنید و سعی کنید بصورت واضحی آنها را به کدهای استاندارد نگاشت کنید. بیش از 70 کد وضعیت HTTP وجود دارد. هر چند اغلب برنامه نویسان همه آنها را نمیشناسند. بنابراین اگر شما کدهای وضعیتی را که رایج نیستند مورد استفاده قرار دهید، استفاده کنندگان از API تان را مجبور میکنید از کدنویسی دست بکشند و در ویکی پدیا دنبال معنی این کد بگردند. بنابراین اکثر APIها از زیر مجموعه کوچکی از این کدها استفاده میکنند. برای مثال Google GData فقط از 10 کد وضعیت استفاده میکند؛ Netflix از 9 و Digg فقط 8 کد.

Google GData
    200 201 304 400 401 403 404 409 410 500
Netflix
    200 201 304 400 401 403 404 412 500
Dig
    200 400 401 403 404 410 500 503

شما باید از چند کد وضعیت در API خود استفاده کنید؟

در واقع اگر دقیق شویم فقط 3 نوع خروجی در هنگام تعامل بین یک برنامه و یک API میتواند وجود داشته باشد:

• همه چیز بدرستی کار میکند - success
• برنامه چیزی را درست انجام نمیدهد - client error
• API کاری را اشتباه انجام میدهد - server error

با به کاربردن 3 کد زیر شروع کنید. اگر نیازتان برطرف نشد به آنها اضافه کنید. اما هرکز از 8 کد فراتر نروید.

• 200-OK
• 400- Bad Request
• 500- Internal Server Error

اگر با کاهش تمام خطاهای خود به 3 خطا احساس راحتی نمیکنید میتوانید از بین 5 کد زیر به خطاهای خود اضافه کنید:

• 201- Created
• 304- Not Modified
• 404- Not Found
• 401- Unauthorized
• 403- Forbidden

این مهم است که کدی که برگردانده میشود بتواند در منطق برنامه استفاده شود. تا جایی که میتوانید پیغام های API مفصل و تشریحی باشند. خلاصه : شرح دهید و از زبان ساده استفاده کنید. هر چقدر میتوانید در مورد علت خطای بوجود آمده توضیحات ارایه کنید. شدیدا ارایه یک لینک به مستندات خطا همانند آنچه Twilio انجام داده است را پیشنهاد میکنیم.

نکاتی در مورد نسخه گذاری

نسخه گذاری یکی از مهمترین مفروضات طراحی API می باشد. هرگز API ای را بدون یک شماره نسخه منتشر نکنید و نسخه را در API خود اجباری کنید. اجازه دهید به متد سه فراهم کننده API برتر نگاهی بیندازیم.

Twilio /2010-04-01/Accounts/
salesforce.com /services/data/v20.0/sobjects/Account
Facbook ?v=1.0

Twilio از برچسب تاریخ در آدرس خود استفاده میکند. در زمان کمپایل برنامه نویس برچسب زمان را در کد خود وارد میکند. این برچسب زمان در تمام درخواستهای HTTP استفاده میشود. وقتی که درخواست میرسد، Twilio یک جستجو انجام میدهد. براساس برچسب تاریخ مشخص میکند که آیا هنوز API معتبر است و سپس درخواست به کد مناسب هدایت میشود. این راهکار بسیار هوشمندانه و جالب است هرچند ممکن است کمی پیچیده باشد. برای مثال ممکن است فهمیدن اینکه برچسب تاریخ مربوط به زمان کمپایل کردن است یا مربوط به زمان انتشار API ممکن است مبهم باشد.

Salesforce.com از v20.0 در میانه آدرس استفاده میکند. ما از بکاربردن حرف V استقبال میکنیم. هرچند از .0 خوشمان نمی آید، زیرا نشاندهنده این است که رابط ممکن است در طول زمان به دفعات مورد تغییر قرار گیرد. منطق پشت رابط ممکن است بسرعت تغییر کند اما خود رابط نباید مرتبا تغییر کند.

Facebook هم از علامت V استفاده میکند اما از ورژن به عنوان یک پارامتر اختیاری استفاده میکند. این کار مشکل زا خواهد بود زیرا به محض اینکه Facebook نسخه جدید API خود را منتشر کند، تمام برنامه هایی که از شماره ورژن استفاده نمیکردند دچار مشکل خواهند شد و مجبور خواهند شد دوباره شماره ورژن را استفاده کنند.

چگونه در مورد شماره های نسخه به صورت اجباری همراه با REST فکر کنیم؟

هرگز API  ای را بدون شماره نسخه منتشر نکنید. همچنین استفاده از ورژن را اجباری کنید. از پیشوند V در ورژن استفاده کنید. تا جایی که میتوانید شماره ورژن را بالاترین وحله آدرس بکار ببرید(/v1/dogs). از یک عدد صحیح ساده استفاده کنید. از ممیز مثل v1.2 استفاده نکنید. زیرا این نوع شماره گذاری به درستی کار نمیکند. شما در حال پیاده سازی یک رابط هستید نه یک برنامه. 

تاچند نسخه باید پشتیبانی شود؟

حداقل از یک نسخه قبلی پشتیبانی کنید. یک ورژن را تا چه زمانی باید حفظ کرد؟ قبل از انقضای یک نسخه به برنامه نویسان اجازه دهید تا یک دوره زمانی از آن استفاده کنند. گاهی اوقات 6 ماه و گاهی اوقات تا 2 سال. این به پلتفرم توسعه دهندگان، نوع برنامه و کاربران آن بستگی دارد. برای مثال، برنامه های موبایل دوره های زمانی طولانی تری نسبت به برنامه های وب دارند.

آیا شماره ورژن و فرمت باید در آدرس باشد یا در هدرها؟

اندیشه های مختلفی در مورد استفاده از  شماره ورژن در هدر وجود دارد. گاهی اوقات افراد برای گذاشتن شماره ورژن در هدر مجبور میشوند زیرا چندین API بطور داخلی وابسته دارند. این اغلب نشانه ای از یک مشکل بزرگتر است، بطور مشخص معمولا نشانه استفاده از ارتباطات داخلی بجای استفاده از یک API ساده قابل استفاده است. این به این معنا نیست که استفاده از شماره ورژن در هدر نشانه طراحی یک API مشکل دارد است. درواقع به دلایل زیادی استفاده از ورژن در هدرها صحیح تر است: از استاندارهای موجود HTTP پیروی میکند، با روح (Fielding's vision) سازگار است، بسیاری از مسایل مربط به API های داخلی را حل میکند و غیره ... . هر چند به نظر دلیل عدم استفاده API های محبوب از هدرها این است که تغییر و هک آن در browser مشکل می باشد.

قواعد ساده ای که ما پیروی میکنیم :

اگر منطق اداره کردن پاسخ برای درخواست API تغییر میکند آن را در داخل آدرس قراردهید تا براحتی دیده شود. اگر برای هر درخواست منطق تغییر نمیکند مانند اطلاعات OAuth آن را در هدر قرار دهید. اینها مثالهایی هستند که منبع یکسانی را نشان میدهند :

dogs/1
Content-Type:application/json
dogs/1
Content-Type:application/xml
dogs/1
Content-Type:application/png

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

صفحه بندی و پاسخ جزیی

پاسخ جزیی به شما اجازه میدهد تا به برنامه نویسان فقط اطلاعاتی که نیاز دارند را بدهید. مثالی در مورد درخواست یک توییت در API تویتر خواهیم زد. شما اطلاعات بسیار بیشتری از آنچه یک برنامه معمولی توییتر میخواهد از API آنها دریافت میکنید،  مثل نام شخص، متن توییت، برچسب زمان، تعداد دفعات توییت مجدد و متاداده فراوان. اجازه دهید به چندین API سرآمد که به برنامه نویسان اجازه استفاده از اطلاعات مورد نیازشان را میدهند شامل گوگل که در ایده پاسخ جزیی پیشتاز است نگاهی بیاندازیم.

LinkedIn
/people:(id,first-name,last-name,industry)

این درخواست id، نام و نام خانوادگی و همچنین زمینه کاری شخص را برمیگرداند. LinkedIn این انتخاب گزینشی را بر اساس این نحو ساده خود-توصیف انجام میدهد. به علاوه این برای یک برنامه نویس مشکل است معنی را با استفاده از موتور جستجو مهندسی معکوس کند.

Facebook 
/Joe.smith/friends?fields=id,name,picture
Google
?fields=title,media:group(media:thumbnail)

گوگل و فیسبوک رهیافت مشابهی دارند که خوب هم کار میکند. آنها هر کدام یک پارامتر اختیاری بنام fields دارند که بعد از آن شما میتوانید نام فیلدهایی که را نیاز دارید بکارببرید. همانطور که مشاهده کردید، شما میتوانید همچنین زیراشیایی را در پاسخ قرار دهید تا اطلاعات دیگری را از منابع اضافی دریافت نمایید. فیلدهای اختیاری را در یک لیست جدا شده با کاما قرار دهید رهیافت گوگل بسیار خوب کار میکند. اینجا می بینید که چگونه میتوانیم با این رهیافت سکهای مورد نیازمان را از API استخراج کنیم:

/dogs?fields=name,color,location

این رهیافت برای خواندن ساده است و یک برنامه نویس میتواند فقط اطلاعاتی که به آن نیاز دارد را انتخاب  نماید. این روش مشکلات پهنای باند را که برای برنامه های موبایل مهم است با کم کردن تعداد تقاضاهای مورد نیاز ، کم میکند.

صفحه بندی داده ها را در پایگاه داده برای برنامه نویس راحت کنید. این همیشه ایده بدی است که تمام منابع یک پایگاه داده را برگردانید. اجازه دهید نگاهی به نحوه مدیریت صفحه بندی در Facebook, Twitter و LinkedIn بیاندازیم. فیسبوک از offset و limit استفاده میکند. تویتر از page و rpp ( رکورد در صفحه ) و لینکدین از start و count استفاده میکند. از نظر ماهوی فیسبوک و لینکدین از روش یکسانی استفاده میکنند.  برای گرفتن رکوردهای 50 تا 75 از هر سیستم ما از دستورات زیر استفاده میکنیم :

• Facebook - offset 50 and limit 25
• Twitter - page 3 and rpp 25
• LinkedIn - start 50 and count 25

از limit و offset استفاده کنید.

ما استفاده از limit و offset را پیشنهاد میکنیم. این روش رایجتر است و در بین دیتابیسهای مطرح بهتر شناخته میشود و برای برنامه نویسان استفاده از آن راحت تر است.

/dogs?limit=25&offset=50

فراداده

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

پیش فرضها چه ؟ قانون ضعیف ما در مورد صفحه بندی پیشفرض limit=10 و offset=0 است. البته که این پیشفرضها به حجم داده های شما بستگی دارند. اگر منابع شما بزرگ است ممکن است بخواهید limit را کمتر از 10 در نظر بگیرید. اگر منابع کوچک باشند ممکن است استفاده از یک limit بزرگتر استفاده میکنیم. بطور خلاصه: از پاسخ گزینشی بوسیله فیلدهای اختیاری در یک لیست جدا شده با کاما پشتیبانی کنید. از limit و offset برای صفحه بندی راحت استفاده کنید.

منابع؟

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

افعالی مانند آنچه در زیر می آید ممکن است در پاسخ خود به منابع ارتباطی نداشته باشند.

• Calculate
• Ttranslate
• Convert

برای مثال وقتی میخواهید یک محاسبه ساده الگوریتمیک مانند میزان مالیات پرداختی، یا میخواهید یک ترجمه انجام دهید و یا یک واحد پولی را به واحد دیگر تبدیل کنید، هیچ کدام نیاز برگرداندن منابع از دیتابیس ندارند.
در این گونه موارد:

از افعال استفاده کنید نه اسمها

برای مثال؛ یک API که 100 یورو را به ین چینی تبدیل میکند:

/convert?from=EUR&to=CNY&amount=100

در مستندات API خود بصورت واضح این سناریوهای متفاوت را مشخص کنید.خیلی ساده بخشی از مستندات خود را بصورت مجزا به مواردی که محاسباتی هستند و نیاز به برگرداندن منابع ندارند اختصاص دهید.

پشتیبانی از فرمتهای مختلف

پیشنهاد میکنیم که بیش از یک فرمت را پشتیبانی کنید که در آن داده های خروجیتان با یک فرمت باشد ولی هر چند فرمت ورودی که نیاز باشد قبول کنید. خیلی وقت ها میتوانید فرآیند نگاشت از یک فرمت به فرمت دیگر را مکانیزه کنید.
در اینجا چندین نحو در مورد فرمت در برخی از API های کلیدی را مشاهده میکنید:

Google Data
?alt=json
Faoursquare
/venue.json
Digg*
Accept:application/json
?type=json

*آرگومان type در صورتی که ارسال شود مقدار هدر را بازنگاری میکند.
Digg به شما دو انتخاب میدهد: در یک متد کاملا مبتنی بر REST  محض از هدر استفاده میکند و یا در متد دیگر از پارامتر type در آدرس استفاده میکند. این میتوان گیج کننده باشد، و حتی الامکان شما باید برای جلوگیری از ابهام مستندات کامل ارایه کنید.
ما راهکار Foursquare را پیشنهاد میکنیم.
برای دریافت فرمت JSON از یک مجموعه یا یک عنصر خاص:

dogs.json
/dogs/1234.json

برنامه نویسان و حتی کاربران عادی هر سیستم عامل با این نحو نقطه گذاری آشنا هستند. این روش فقط به یک کاراکتر اضافی نیاز دارد.
در مورد فرمت های پیش فرض چه؟
به نظر من، JSON برنده فرمتهای پیش فرض است. JSON نزدیک چیز به زبان عمومی است. حتی اگر پس زمینه سیستم با رابی، PHP، java و پایتون و یا غیره ساخته شده باشد، بیشتر پروژه ها در پیش زمینه از جاوااسکریپت استفاده میکنند. همچنین این فرمت مزیت مختصر بودن را نسبت به ‌XML دارد.
در مورد اسم ویژگیها چه؟
تا بحال در مورد فرمتها، پشتیبانی از چندین فرمت و کار با JSON به عنوان فرمت پیشفرض صحبت کردیم. این بار میخواهیم در مورد آنچه که در پاسخ برگردانده میشود صحبت کنیم.
شما یک شی با صفات داده در آن دارید. چگونه باید آنها را نامگذاری کنید؟
در اینجا چندین پاسخ APIاز API های پیشتاز را می بینیم:

Twitter
"created_at":"Thu Nov 03 05:19;38 +0000 
2011"
Bing
"DateTime":2011-10-29T09:335:0Z"
Foursquare
"createdAt":1320296464

هر کدام از آنها از قرارداد کد نویسی متفاوتی استفاده میکنند. هر چند رهیافت Twitter برای من به عنوان یک توسعه دهنده Ruby on Rails آشناتر است، اما از نظر ما رهیافت Foursquare از بقیه بهتر است.
پاسخ API چگونه در کد استفاده میشود؟ شما پاسخ را Parse میکنید. آنچه که برمیگردد یک شی را مقداردهی میکند. چیزی شبیه این :
var myObject=JSON.parse(response);
اگر شما از رهیافت Bing و Twitter استفاده کنید، کد شما مشابه خواهد  بود.
پیشنهاد ها:
ازJSON به عنوان فرمت پیشفرض استفاده کنید.
از نحو جاوااسکریپت برای نامگذاری صفات استفاده کنید.
از حروف بزرگ به عنوان جدا کننده استفاده کنید(CamelCase)
از حروف بزرگ یا کوچک بسته به نوع شی استفاده کنید.
این هیافت منجر به این میشود که کد شما چیزی شبیه آنچه در زیر می آید میشود:
"createdAt":13320296464
timing=myObject.createdAt;

نکاتی در مورد جستجو

در حالیکه یک جستجوی ساده با یک API مبتنی بر منابع به سادگی میتواند مدل شود، جستجوی پیچیده تر در میان منابع مختلف نیاز به طرحی متفاوت دارد.
اگر میخواهید یک جستجوی کلی در میان منابع انجام دهید ما استفاده از مدل گوگل را پیشنهاد میکنیم:
Global search
/search?q=fluffy+fur
در اینجا search یک فعل است و ?q کوئری را ارایه میدهد.
Scoped search
برای اضافه کردن وحله به جستجوی خود، میتوانید وحله خود را به ابتدای جستجو بیافزایید. برای مثال جستجوی سگهایی که صاحبشان دارای ID 5678 می باشد:
/owners/5678/dogs?q=fluffy+fur
دقت کنید که ما از عبارت search را بصورت مصرح بکار نبردیم و از پارامتر q برای نمایش جستجوی وحله ای استفاده کرده ایم.
نتایج فرمت بندی شده
برای جستجوی هریک از پاسخهای مبتنی بر فعل، میتوانید فرمت را بصورت زیر اضافه کنید
/search.xml?q=fluffy+fur
تحکیم درخواستهای API در یک زیردامنه
تا بحال در مورد چیزهایی که بعد از بالاترین سطح دامنه می آمدند صحبت کردیم. این بار نوبت به چیزهایی میرسد که در آنسوی آدرس قرار دارد.
نحوه عمل فیسبوک، فوراسکور و تویتر را بررسی میکنیم:
فیس بوک از دو API استفاده میکند. آنها با api.facebook.com شروع کردند و در ادامه آن را حول محور گراف اجتماعی به graph.facebook.com تغییر دادند.
graph.facebook.com
api.facebook.com
فوراسکور فقط یک API دارد.
api.foursquare.com
تویتر سه APIدارد. دو تا از آنها بر جستجو و استریمینگ متمرکز شده اند.
stream.twitter.com
search.twitter.com
api.twitter.com
فهم اینکه چگونه فیسبوک و توییتر به چیزی بیشتر از یک API رسیده اند ساده است. با گذشت زمان و اقتضای کسب و کار کارهای زیادی انجام میشود و همچنین تنظیم یک ‌مدخل CName در DNS شما برای اینکه تقاضاها را به کلاسترهای متفاوت ارسال کند کار ساده ایست.
اما اگر ما درحال تصمیم گیری باشیم و همچنین علاقه برنامه نویسان را در نظر داشته باشیم، پیروی از Foursquare را پیشنهاد میکنیم:
تمام درخواستهای API را در یک زیر دامنه قرار دهید.
این برای برنامه نویسانی که میخواهند برنامه های جالبی با استفاده از API شما بسازند، تمیزتر راحتر و واضح تر خواهد بود. همچنین فیسبوک، فوراسکور و توئیتر همگی پورتالهایی مختص توسعه دهندگان دارند.
developers.facebook.com
developers.foursquare.com
dve.twitter.com
چگونه همه اینها را سازماندهی کنیم؟
دروازه API شما باید یک دامنه سطح اول باشد. برای مثال api.teachdogrest.com.
همگام با حفظ روح REST، پورتال توسعه دهندگان شما باید از این الگو پیروی کند: developers.yourtopleveldomain. برای مثال developers.teachdogrest.com
از redirect استفاده کنید.
اگر از درخواستهایی که برنامه نویسان به API‌ ارسال میکنند احساس میکنید که باید به بخش خاصی هدایت شوند میتوانید از redirect استفاده کنید.
فرض کنید برنامه نویس در مرورگر خود عبارت api.teachdogrest.com‌ را تایپ میکند اما هیچ اطلاعاتی برای درخواست GET وجود ندارد، احتمالا میتوانید کاربر را به سمت پورتال برنامه نویسان هدایت کنید.

api->developers
dev->developers
developer->developers

نکاتی برای مدیریت استثناها

تا اینجا در مورد خط اصلی و رفتارهای استاندارد بحث کرده ایم. در اینجا برخی از استانات را کاربر API ما نمیتواند اداره کند بررسی میکنیم. برای مثال گاهی اوقات مشتریان API نمیتوانند کدهای HTTP را تفسیر کنند و یا تعداد محدودی از این کدها را پشتیبانی میکنند. راههای مدیریت چنین موقعیتهایی و همچنین محدودیتهای که برخی از کاربران خاص API دارند چیست؟ وقتی که مشتری کدهای خطای HTTP را رد میکند این در میان ورژنهای مختلف Adobe Flash معمول است که اگر شما هر کد HTTP به غیر از کد 200 در پاسخ به آن ارسال کنید، Flash آن پاسخ را رد میکند و کد خطا را به کاربرنهایی در برنامه نشان میدهد. بنابراین توسعه دهنده برنامه فرصت رد کردن کد خطا را نخواهد داشت. توسعه دهندگان نیاز دارند تا API به طریقی این مورد را پشتیبانی کند. Twitter این کار را به صورت عالی انجام میدهد. آنها یک پارامتر اختیاری بنام suppress_response_codes دارند. اگر این پارامتر با مقدار true مقداردهی شود پاسخ HTTP همیشه کد 200 خواهد بود.

/public_timelines.json?suppress_respnse_codes=true
HTTP satus code: 200 {"error":"Could not authenticate you."}

توجه کنید که این پارامتر طول زیادی دارد و آنها میتوانستند از پارامتر کوچکتری مثل src استفاده کنند ولی ترجیح داده اند که از یک پارامتر طولانی و واضح استفاده کنند. پیشنهادات کلی : از suppress_response_codes=true استفاده کنید. کد HTTP دیگر فقط برای کد نیست قوانین مدیریت خطاها از فصل پیش را تغییر دادیم. در این مبحث کد HTTP دیگر فقط مختص کد نیست و میتواند در نظر گرفته نشود و مشتریان برنامه نیاز نیست که هرگز کد HTTP را چک کنند، چرا که این کد همیشه یکسان است. هر کد پاسخ HTTP را که باید داشته باشیم را در پیغام ارسالی قرار دهید. در مثال زیر کد پاسخ 401 است. شما میتوانید آن را در پیغام پاسخ ببینید. بعلاوه این پاسخ شامل کدهای خطای اضافی و اطلاعات مفصل در پیغام میشود.

Always return OK
/dogs?suppress_response_codes=true
Code for ignoring
200 -OK
Message for people & code
{"response_code":401,"message":"Verbose, plain language description of the problem with hints about how to fix it."
"more_info":"http://dev.tecachdogrest.com/errors/12345","code":12345}

هنگامی که مشتری فقط از متدهای محدود HTTP پشتیبانی میکند خیلی وقتها ممکن است که مشتری API فقط از متدهای POST , GET پشتیبانی کند و از متدهای PUT و DELETE پشتیبانی نکند. برای اینکه یکپارچگی متدهای چهارگانه HTTP را حفظ کنید ما استفاده از متدی که توسعه دهندگان Ruby on Rails بکار میبرند را پیشنهاد میکنیم: متد را یک قسمت اختیاری از آدرس قرار دهید. به اینصورت که فعل HTTP همیشه GET باشد ولی برنامه نویس بتواند متدهای محض HTTP را در آدرس استفاده کند و یک API تمیز RESTful داشته باشیم.

Create
/dogs?method=post
Read
/dogs
Update
/dogs/1234?method=put&location=park
Delete
/dogs/1234?method=delete

اخطار :‌استفاده از متد ‌GET برای این کاربرد میتواند خطرناک باشد زیرا اگر آدرس در یک صفحه وب قرار گیرد خزنده هایی مثل Googlebot میتوانند بصورت ناآگاهانه محتوایی را خراب کنند یا از بین ببرند. از نحوه پیاده سازی این قابلیت در برنامه خود آگاهی کامل داشته باشید. احراز هویت (authentication) بحث زیادی در مورد احراز هویت وجود دارد. من و همکارانم در Apigee کاملا با هم در مورد نحوه مدیریت احراز هویت هم عقیده نیستیم. به هر حال آنچه در ادامه می آید نظر من است. اجازه دهید به سه سرویس پیشرو نگاهی بیاندازیم و ببینیم که هر کدام از آنها چگونه به صورت متفاوتی احراز هویت کاربران را مدیریت میکنند.

PyaPal
Permissions Service API
Facebook
OAuth 2.0
Twitter
OAuth 1.0a

در نظر داشته باشید که API اختصاصی PyaPal مدتها قبل از OAuth وجود داشته است. شما باید چه کنید؟ از آخرین و بزرگترین OAuth استفاده کنید ( در زمان نوشتن این مطلب OAuth 2.0). این بدین معناست که برنامه های وب یا موبایل که از API استفاده میکنند نیاز به اشتراک گذاری پسوردها ندارند. این به فراهم آورنده API اجازه میدهد که برای کاربران انفرادی در کل برنامه بدون اینکه نیاز باشد کاربر پسورد خود را عوض کند از توکن ها استفاده کنند. این در هنگامی که یک برنامه موبایل مورد تهاجم قرار میگیرد و یا یک برنامه خرابکار تشخیص داده میشود مهم است. در کل، OAuth 2.0 به معنی امنیت بیشتر و تجربه کاربری بهتر برای کاربران وب و موبایل است. از چیزهایی شبیه OAuth ولی متفاوت با آن استفاده نکنید. برای برنامه نویسان ناخوشایند خواهد بود اگر از کتابخانه OAuth در زبان برنامه نویسی خود بخاطر نسخه متفاوت شما نتوانند استفاده کنند. تقاضاها از API شما اجازه دهید نگاهی به چند درخواست و پاسخ از API فرضی خود نگاهی بیاندازیم.

Create a brown dog named Al
POST /dogs
name=Al&furColor=brown
Response
200 OK
{
"dog":{
"id":"1234",
"name":"Al",
"furColor":"brown"}
}
Rename Al to Rover - Update
PUT /dogs/1234
name=Rover
Response
200 OK

{
"dog":{
"id":"1234",
"name":"Rover",
"furColor":"brown"}
}
Tell me about a particular dog
GET /dogs/1234
Response 

200 OK

{
"dog":{
"id":"1234",
"name":"Rover",
"furColor":"brown"}
}
Tell me about all the dogs
Get /dogs
Response

200 OK

{
"dogs":[{
"dog':{
"id":"1233",
"name":"Fido",
"furColor":"white"}},


{"dog":{


"id":"1234",
"name":"Rover",
"furColor":"brown"}
}}]

"_metadata":
[{"totalCount":327,"limit":25,"offset":100}]
}
Delete Rover :-(
DELETE /dogs/1234
Response
200 OK

API های شلوغ

بیایید به برنامه نویسانی که از API ما استفاده خواهند کرد فکر کنیم. نحوه استفاده برنامه نویسان از API خود را تصور کنید. هنگام طراحی API و منابع خود، سعی کنید تصور کنید که برنامه نویسان از آن برای ساخت یک رابط کاربری، یک برنامه iPhone و یا برنامه های دیگر استفاده خواهند کرد. برخی از طراحی های API بسیار شلوغ هستند. به این معنی که برای ساخت یک برنامه یا UI ساده باید تعداد بسیاری زیادی فراخوانی API  به سرور داشته باشید. تیم طراحی API گاهی میتواند تصمیم بگیرد که بجای ساختن یک API مبتنی بر منبع RESTful فقط از 3 یا 4 متد getter , setter به شیوه جاوا برای یک رابط کاربری خاص استفاده کند. ما این را پیشنهاد نمیکنیم.

میتوانید یک RESTful API طراحی کنید و همچنان از شلوغی پرهیز کنید. کاملاRESTful باشید اما میانبرهایی ایجاد کنید ابتدا API و منابع خود را براساس اصول طراحی RESTful طراحی کنید و سپس میانبرهایی ایجاد نمایید. کدام نوع میانبرها؟ این را در نظر بگیرید که 80 درصد از تمام برنامه های شما به برخی از ترکیبها در پاسخ نیازمند هستند، سپس انواع تقاضا برای آنچه نیاز دارند را طراحی کنید. فقط به یاد داشته باشید که ابتدا مورد اول را انجام دهید یعنی طراحی کاملا RESTful. از مزایای نحو پاسخ جزیی استفاده کنید. نحو پاسخ جزیی که در بخش قبلی بحث شد میتواند کمک کند. برای جلوگیری از ایجاد آدرسهای پایه غیر تکی میتوانید از شیوه پاسخ جزیی استفاده کنید تا  منابع مستقل و وابسته را ارایه دهید. در مورد مثال API سگ، سگها با صاحبان خود که آنها نیز با دامپزشکان رابطه داشتند. از جاسازی پاسخ جزیی با استفاده از علامت نقطه استفاده کنید و فقط اطلاعاتی را که نیاز است برگردانید.

/owners/5678?fields=name,dogs.name

ارایه یک SDK این سوال رایجی برای فراهم آوردندگان API است - آیا نیاز است که برای API خود SDK و کتابخانه کد فراهم کنیم؟ اگر API شما از نمونه های خوب طراحی استفاده میکند، خود شمول، مبتنی بر استاندارد و خوب مستند شده است، برنامه نویسان میتوانند بدون نیاز به SDK جداگانه از آن استفاده کنند. البته استفاده از نمونه کدهای خوب مستند شده کاملا ضروری است. اما در سوی دیگر اگر درست کردن یک رابط کاربری به اطلاعات زیادی در مورد حوزه عملکرد نرم افزار نیاز داشته باشد چه؟ این میتواند حتی برای برنامه نویسانی که بر روی یک UI یا برنامه روی یک API با حوزه عمل بسیار ساده کار میکنند مسئله چالش انگیزی باشد. برای مثال Twitter را با موضوع اولیه آن یک پیغام 140 کاراکتری در نظر بگیرید. شما نباید برای غلبه بر مشکل اطلاعات در مورد حوزه برنامه، API  خود را تغییر دهید. بجای آن میتوانید API خود را با کتابخانه های کد و کیتهای توسعه نرم افزار(SDK) پشتیبانی کنید.

در اینصورت دیگر نیازی نیست که طراحی API خود را سنگین کنید. اغلب بیشتر آنچه که نیاز است در سمت مشتری انجام میپذیرد و شما میتوانید آن را به SDK تحمیل کنید. SDK میتواند کد ویژه پلتفرم (platform-specific) فراهم کد که برنامه نویسان در برنامه های خود از آن استفاده نمایند و شما API خود را تمیز نگه دارید. دلایل دیگری که میتوانند باعث شوند تا یک SDK برای API خود ایجاد کنید عبارتند از: تطبیق پذیری سریع با یک پلتفرم خاص. ( برای مثال Objective C SDK برای iPhone) بسیاری از برنامه نویسان با تجربه فقط با Objectve C کار میکنند بنابراین یک SDK میتواند مفید واقع شود. سختی تجمیع برای کارکردن با API خود را کم کنید اگر موارد استفاده کلیدی از API پیچیده هستند و یا نیازدارند که با استاندار خاصی در سمت مشتری انجام شوند میتوانید از SDK استفاده کنید. یک SDK میتواند کد بد یا غیر ضروری (که میتواند باعث کاهش سرعت سرویس شود) را کاهش دهد به عنوان یک منبع برنامه نویس SDK های خوب نیروی اجباری برای سورس کد خوب و مستندات هستند. yahoo و Paypal مثالهای خوبی هستند:

Yahoo! http://developer.yahoo.com/social/sdk
Pyapal https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&_ID=developer/library_download_sdks

برای فروش API خود به گروهی خاص شما SDK خود را به صفحه پلاگین یا مثالهای یک جامعه موجود برنامه نویسان یک پلتفرم خاص آپلود میکنید. الگوی طراحی API Facade حالا که به نقطه رسیدیم ممکن است از خود بپرسید از منظر معماری چگونه باید بیاندیشیدیم؟ چگونه میتوانیم تمام این الگوهای عملی را بکارببریم و سرویسها و سیستمهای داخلی را طوری برای برنامه نویسان ارایه دهیم که همچنان یک API قابل تکرار و نگهداری داشته باشیم؟ سیستمهای پشت صحنه موجود اغلب برای ارایه مستقیم به توسعه دهندگان بسیار پیچیده هستند. آنها پایدار و قابل اتکا هستند اما اغلب برپایه تکنولوژیهای قدیمی می باشند و همیشه قابل ارایه بصورت استاندارهای وب مثل HTTP نیستند. همچنین این سیستمها میتوانند ارتباطات داخلی پیچیده ای داشته باشند که به آرامی تغییر میکنند و این بدین معناست که نمیتوانند به سرعت به نیازی در حال تغییر توسعه دهندگان برنامه های موبایل پاسخ دهند. در واقع، مسئله طراحی یک API برای یک سیستم بزرگ نیست بلکه مسئله طراحی API برای آرایه ای از سیستمهای مکمل می باشد که همگی نیاز دارند API ارزشمندی را به توسعه دهنده ارایه دهند. مفید خواهد بود که درباره چند ضد الگو که دیده ایم صحبت کنیم. اجازه دهید با هم علت اینکه از نظر ما این الگو جواب نمیدهند را بررسی کنیم.

رهیافت Build Up

برنامه نویس اجزای اصلی یک سیستم بزرگ را میسازد و لایه تجزیه کننده XML بر روی آن ارایه میکند. این رهیافت از آن جهت که میتواند به سرعت در ورژن 1 فروخته شود شاید ارزشمند باشد. همچنین تیم API شما درک مشترکی از سیستم دارند. اما جزییات سیستم داخلی در وحله اشیا داخلی کاملا مستحکم شده اند و میتوانند برای توسعه دهندگان خارجی مبهم باشند. همچنین شما در حال ارایه جزئیات معماری داخلی خود هستید که به ندرت میتواند ایده خوبی باشد. این رهیافت میتواند انعطاف پذیر باشد زیر شما یک نگاشت یک به یک از آن چه که سیستم انجام میدهد به آنچه که به API ارایه میدهد دارید. بطور خلاصه ساخت یک سیستم از رکوردها به یک API میتواند باعث افزایش پیچیدگی شود.

رهیافت کمیته استانداردها

اغلب سیستمهای داخلی صاحبان متفاوتی دارند و به وسیله افراد مختلفیار اداره میشود که دیدگاههای متفاوتی در مورد اینکه سیستم باید چگونه کارکند، دارند. طراحی یک API به وسیله کمیته استانداردها اغلب شامل ایجاد سند استانداردها میشود که طرح و آدرسها و چنین چیزهایی را مشخص میکند. تمام توسعه دهندگان براساس آن هدف مشترک کار میکنند. از مزیتهای این رهیافت این است که به سرعت ورژن یک را ایجاد میکنید. همچنین میتوانید روح واحدی را در میان تمام سازمان احساس کنید و استراتژی مشخصی داشته باشید که در یک سازمان بزرگ با همکاران و شرکای متعدد میتواند بسیار مفید واقع شود. از معایب این رهیافت آن است که میتواند بسیار  کند شود. حتی اگر شما سند را بسیار سریع آماده کرده باشید، مجبور کردن همه به اینکه آن را پیاده سازی کنند میتواند بسیار کند باشد. همچنین به علت تعداد زیاد توافقات و تعهدات این رهیافت میتواند باعث ایجاد یک طراحی متوسط شود.

رهیافت Copy Cat

این روش را گاهی در شرکتهایی که از بازار عقب افتاده اند میبینیم. برای مثال وقتی رقیب اصلی آنها یک راه حل معرفی کرده است. در این رهیافت نیز شما به سرعت ورژن یک را ارایه میکند و یک منحنی سازگاری سریع با برنامه نویسان به علت آشنا بودن آنها با API رقیب دارید. هر چند ممکن است شما با یک محصول نا متمایز که در بازار API ها به عنوان یک پیشنهاد نامرغوب شناخته شود کار را تمام کنید. اما در واقع شما از ارایه ارزشهای کلیدی خود و تمایز با دیگران به علت کپی برداری از API دیگران باز میمانید.

راه حل  - الگوی API facade بهترین راه حل با تفکر در مورد اساس مدیریت تولید شروع میشود. محصول شما ( API شما) باید معتبر، کاربردی و متمایز باشد. مدیر تولید شما یک عضو کلیدی از تیم API شماست. بعد از اینکه مدیر تولید تصمیم گرفت که تصویر بزرگ باید چگونه باشد نوبت به معماران میرسد. ما پیشنهاد میکنیم که از الگوی API facde استفاده کنید. این الگو یک لایه مجازی بین رابط در بالا و پیاده سازی API در پایین میدهد. شما در واقع یک نما (facade) از آنچه که باید API شما از دید یک برنامه نویس به نظر برسد ایجاد میکنید. برنامه نویس و برنامه ای که از API استفاده میکنند در بالا قرار میگیرند. API facade برنامه نویس و برنامه را از API جدا میکند. یک طراحی تمیز در facde به شما اجازه میدهد یک مسئله بسیار سخت را به چند مسئله ساده تر تقسیم کنید. "از الگوی facde وقتی استفاده کنید که میخواهید یک رابط ساده برای یک زیرسیستم پیچیده ایجاد کنید. زیر سیستمها اغلب از سیستمی که در آن قرار دارند پیچیده تر هستند."

پیاده سازی یک الگوی API facade از سه گام اساسی تشکیل میشود.

1. API ایده آل خود را طراحی کنید. آدرسها، پارامترهای درخواست و پاسخ، هدرها و غیره را طراحی کنید.
2. طراحی را با داده ها پیاده سازی کنید. این توسعه دهندگان برنامه اجازه میدهد که از API شما استفاده کنند و به شما بازخورد بدهند حتی قبل از اینکه API به سیستمهای داخلی متصل گردد.
3. بین سیستمهای داخلی و facade ارتباط برقرار کنید.

استفاده از این الگو مسئله بزرگ شما را به سه مسئله کوچک تقسیم میکند. اگر تلاش کنید که یک مشکل بزرگ را حل کنید، آنگاه با  کدنویسی شروع خواهید کرد و تلاش  خواهید کرد که با منطق تجاری  خود را روی یک API تمیز بسازید. احتمالا اشیا، جدولها، فیدهای RSS و غیره را از مخازن خود ارایه خواهید کرد که به XML نگاشت شده اند قبل از اینکه به فرمت قابل استفاده در برنامه ارایه شوند. این رهیافت یک رهیافت ماشین به ماشین متمرکز بر برنامه می باشد و درست انجام دادن آن مشکل است.

استفاده از الگوی facade برای عبور از رهیافت مخزن به شما کمک خواهد کرد. ابتدا میتوانید با حول هر یک از مراحل سه گانه جداگانه مانور دهید و افرادی داشته باشید که به صورت واضح رهیافت عملگرای شما را در می یابند. دوما مسیر حرکت از سمت برنامه به سمت توسعه دهنده تغییر میکند و هدف این میشود که توسعه دهنده برنامه براحتی از  API شما استفاده کند. facade به علت جایی از معماری که در آن قرار میگیرد، میتواند یک شاهراه عالی باشد. حالا شما میتوانید از facade برای پیاده سازی الگوهای رایج (برای صفحه بندی، پرس و جوها، ترتیب، مرتب سازی و ...)، احراز هویت، تعیین دسترسی، نسخه بندی  و غیره استفاده کنید.

مزیت دیگر آن برای تیم API این است که براحتی میتواند به سناریوهای مختلف اعم از اینکه توسعه دهنده داخلی باشد، شریک تجاری باشد و یا غیره آداپته شود. تیم API میتواند با نیازهای در حال تغییر برنامه نویسان از جمله پروتکلها و زبانهای همیشه در حال تغییر حرکت کند. همچنین گسترش API با ساخت توانایی های بیشتر برنامه شما و یا اضافه کردن افزونه ها به سیستم های موجود آسانتر خواهد بود.

منبع :‌apigee.com