یک API خوب مثل یک قرارداد است؛ تیمهای دیگر بر پایهٔ آن کد مینویسند و تغییر بیخبر آن، کار آنها را میشکند. طراحی API خوب یعنی ساختن چیزی که هم امروز قابلفهم باشد و هم در آینده بدون شکستن قرارداد قابل توسعه بماند. این کار به انضباط و دوراندیشی نیاز دارد، نه فقط دانش فنی.
ثبات و پیشبینیپذیری، مهمترین ویژگی یک API است. نامگذاری منابع و فیلدها باید یکدست باشد، افعال HTTP طبق معنای استانداردشان به کار روند و ساختار پاسخها در سراسر API یک الگو داشته باشد. وقتی توسعهدهنده رفتار یک نقطهٔ پایانی را یاد گرفت، باید بتواند رفتار بقیه را حدس بزند.
مدیریت خطا اغلب دستکم گرفته میشود اما تجربهٔ توسعهدهنده را میسازد. کد وضعیت HTTP باید درست انتخاب شود و بدنهٔ پاسخ خطا باید پیامی روشن و ماشینخوان بدهد که مشخص کند چه چیزی و چرا اشتباه بوده. خطای مبهم، ساعتها وقت تیم مصرفکننده را تلف میکند.
نسخهبندی از روز اول باید در نظر گرفته شود، چون API روزی تغییر خواهد کرد. با گنجاندن نسخه در مسیر، میتوان نسخهٔ جدید را بدون شکستن مصرفکنندگان فعلی منتشر کرد. در کنار آن، مستندات دقیق و بهروز — ترجیحاً تولیدشده از خود کد با استانداردی مثل OpenAPI — تضمین میکند مستندات هرگز از واقعیت عقب نماند.