מדריך לעיצוב API

יומן שינויים

מבוא

זהו מדריך כללי לעיצוב של ממשקי API ברשת. הוא נמצא בשימוש בתוך Google מאז 2014, והוא המדריך ש-Google פועלת לפיו כשהיא מתכננת ממשקי Cloud API וממשקי Google API אחרים. אנחנו משתפים את מדריך העיצוב הזה כדי לספק מידע למפתחים חיצוניים ולעזור לנו לעבוד יחד בצורה קלה יותר.

מפתחים של Cloud Endpoints יכולים להיעזר במדריך הזה במיוחד כשהם מתכננים ממשקי gRPC API, ואנחנו ממליצים להם מאוד להשתמש בעקרונות התכנון האלה. עם זאת, אנחנו לא מחייבים להשתמש בו. אפשר להשתמש ב-Cloud Endpoints וב-gRPC בלי לפעול לפי המדריך.

המדריך הזה רלוונטי גם ל-REST APIs וגם ל-RPC APIs, עם דגש ספציפי על gRPC APIs. ממשקי gRPC API משתמשים ב-Protocol Buffers כדי להגדיר את משטח ה-API שלהם וב-API Service Configuration כדי להגדיר את שירותי ה-API שלהם, כולל מיפוי HTTP, רישום ביומן ומעקב. תכונות מיפוי HTTP משמשות את ממשקי ה-API של Google ואת ממשקי ה-API של Cloud Endpoints gRPC לטרנסקוד של JSON/HTTP ל-Protocol Buffers/RPC.

המדריך הזה הוא מסמך דינמי, ונוסיף לו חומרים בהמשך ככל שנקבל אישור על סגנונות ודפוסי עיצוב חדשים. לכן, אף פעם לא נסיים את המדריך הזה, ותמיד יהיה מקום לשיפורים בעיצוב ממשקי ה-API.

מוסכמות שמשמשות במדריך הזה

מילות המפתח לציון רמת הדרישה MUST,‏ MUST NOT,‏ REQUIRED,‏ SHALL,‏ SHALL NOT,‏ SHOULD,‏ SHOULD NOT,‏ RECOMMENDED,‏ MAY ו-OPTIONAL שמופיעות במסמך הזה, מתפרשות כמו שמתואר ב-RFC 2119.

במסמך הזה, מילות מפתח כאלה מודגשות באמצעות גופן מודגש.

חלקים

עיצוב מבוסס-משאבים

מידע על הטמעה של עיצוב מבוסס-משאבים עבור ממשקי API של RPC ו-REST זמין במאמר AIP-121.

שמות המשאבים

מידע על שמות משאבים זמין במאמר AIP-122.

שיטות רגילות

מידע כללי על שיטות זמין במאמר AIP-130.

מידע על שיטות סטנדרטיות זמין ב-AIP הבאים:

  • ל-Get, אפשר לעיין ב-AIP-131
  • למידע על List, אפשר לעיין ב-AIP-132
  • למידע על Create, אפשר לעיין ב-AIP-133
  • למידע על Update, אפשר לעיין ב-AIP-134
  • לגבי Delete, אפשר לעיין ב-AIP-135

שיטות בהתאמה אישית

מידע על שיטות מותאמות אישית זמין במאמר AIP-136.

נושאים נוספים

מידע על הנושאים הבאים זמין ב-AIP שקשור אליהם.

מידע על הנושאים הבאים מופיע בדפים הרלוונטיים במדריך הזה.

הבא
Directory structure