שירותי API בדרך כלל משתמשים בקובצי .proto כדי להגדיר את פלטפורמת ה-API ובקובצי .yaml כדי להגדיר את שירות ה-API. לכל שירות API חייב להיות ספריית API בתוך מאגר API. ספריית ה-API צריכה להכיל את כל קובצי הגדרת ה-API וסקריפטים של build.
לכל ספריית API צריך להיות הפריסה הסטנדרטית הבאה:
ספריית API
דרישות מוקדמות למאגר
-
BUILD– קובץ ה-build. -
METADATA– קובץ המטא-נתונים של הגרסה. -
OWNERS– הבעלים של ספריית ה-API. -
README.md– המידע הכללי על שירות ה-API.
-
קובצי תצורה
-
{service}.yaml– קובץ ההגדרות של שירות הבסיס, שהוא ייצוג YAML של הודעת הפרוטוgoogle.api.Service. -
prod.yaml– קובץ ההגדרות של שירות הדלתא של הסביבה הפרודקטיבית. -
staging.yaml– קובץ ההגדרות של שירות הדלתא של הסביבה הזמנית. -
test.yaml– קובץ התצורה של שירות הדלתא לבדיקה. -
local.yaml– קובץ התצורה של שירות הדלתא המקומי.
-
קבצים של תיעוד
-
doc/*– קבצי התיעוד הטכני. הם צריכים להיות בפורמט Markdown.
-
הגדרות הממשק
-
v[0-9]*/*– כל ספרייה כזו מכילה גרסה ראשית של ה-API, בעיקר קובצי פרוטו וסקריפטים של build. -
{subapi}/v[0-9]*/*– כל ספרייה{subapi}מכילה הגדרת ממשק של API משני. לכל ממשק API משני יכולה להיות גרסה ראשית משלו. -
type/*– קובצי proto שמכילים סוגים שמשותפים בין ממשקי API שונים, בין גרסאות שונות של אותו API או בין ה-API לבין הטמעת השירות. הגדרות הסוגים בקטעtype/*לא אמורות לכלול שינויים שגורמים לבעיות תאימות אחרי שהן מתפרסמות.
-
הגדרות של ממשקי Google API ציבוריים מתפרסמות ב-GitHub. אפשר לעיין במאגר Google APIs.