ממשק API הוא רק טוב כמו התיעוד שלו, אז ודא שהממשק שלך ניתן לגילוי עם הוראות איכותיות ופרטים חשובים אחרים.
ארגונים נוספים ממנפים את הכוח של ממשקי API כדי לייעל את העסק שלהם. ממשקי API הפכו לדרך לפתוח ערך ולספק שירות נוסף.
למרות הפופולריות הכללית שלהם, לא כל API הוא הצלחה. האימוץ והשימוש ב-API קובעים במידה רבה את הצלחתו. כדי להגביר את האימוץ, ה-API שלך צריך להיות קל למצוא ולהשתמש.
הדרך הטובה ביותר לעשות זאת היא על ידי תיעוד ה-API שלך בפירוט. זה כולל פירוט של רכיבים קריטיים כדי להקל עליהם להבין אותם. גלה כמה מהרכיבים שאתה צריך לכלול בתיעוד ה-API שלך.
מהו תיעוד API?
תיעוד API הוא תוכן טכני שמתאר API בפירוט. זהו מדריך המכיל את כל המידע הנדרש לעבודה עם ה-API. המסמך מכסה את מחזור החיים של ה-API והוראות על שילוב ושימוש ברכיביו.
תיעוד API מכסה תיאורי משאבים, נקודות קצה, שיטות, בקשות ודוגמאות תגובה. זה יכול לכלול גם מדריכים מעשיים ומדריכים המראים למשתמשים כיצד לשלב אותו. חקירת כל סעיף מעניקה למשתמשים הבנה מוצקה של שילוב ושימוש ב-API.
עורכים כמו Google Docs היו בעבר בשימוש נרחב לתיעוד API מקצועי. כיום, ישנם כלים מתקדמים יותר כמו Document 360, Confluence ו-GitHub Pages. כלים אלה עוזרים לשלב טקסט וקוד לזרימות עבודה קלות יותר.
1. סקירה כללית ומטרת ה-API
השלב הראשון בתיעוד ממשק API הוא לאפשר למשתמשים לדעת במה מדובר. כלול מידע על סוג המשאבים שהוא מספק. לממשקי API יש בדרך כלל משאבים שונים שהם מחזירים, כך שהמשתמש יכול לבקש את מה שהוא צריך.
התיאור קצר, בדרך כלל אחד עד שלושה משפטים המתארים את המשאב. תאר את המשאב הזמין, את נקודות הקצה ואת השיטות המצורפות לכל נקודת קצה. כמפתח API, אתה מתאר בצורה הטובה ביותר את הרכיבים, הפונקציונליות ומקרה השימוש שלו.
הנה דוגמה לתיאור של ה-API של Airbnb:
2. שיטות אימות והרשאה
ממשקי API מטפלים באלפי בקשות ובכמויות אדירות של נתונים. אימות הוא אחת הדרכים להבטיח שהנתונים של ה-API והמשתמשים שלך מאובטחים מפני האקרים. אימות API מאמת את זהות המשתמש ומעניק להם גישה למשאבים.
ישנן מספר דרכים להבטיח אבטחת נקודות קצה. רוב ממשקי ה-API משתמשים במפתח API. זוהי מחרוזת של תווים שמשתמש יכול ליצור מהאתר ולהשתמש בו לצורך אימות.
תיעוד ה-API אמור להדריך את המשתמשים כיצד לאמת ולאשר את זהותם. התרשים הבא מציג מידע על אימות API של Twitter.
3. נקודות קצה, דפוסי URI ושיטות HTTP
בסעיף זה, הדגימו כיצד לגשת למשאב. נקודות הקצה מציגות רק את סוף הנתיב, ומכאן שמם. הם מראים גישה למשאב ו שיטות HTTP נקודת הקצה מקיימת אינטראקציה עם, כלומר GET, POST או DELETE.
למשאב אחד יש כנראה מגוון נקודות קצה. לכל אחד דרך ושיטה אחרת. לנקודות קצה יש בדרך כלל תיאור קצר של מטרתן ודפוס כתובת אתר.
דוגמת הקוד הבאה מציגה נקודת קצה של משתמש GET באינסטגרם.
תשיג לי? fields={fields}&access_token={access-token}4. פורמטים של בקשה ותגובה
עליך לתעד את הפורמטים של הבקשה והתגובה כדי שהמשתמש ידע למה לצפות. הבקשה היא כתובת URL מלקוח המבקש משאב, בעוד שהתגובה היא משוב מהשרת.
להלן בקשה לדוגמה שתוכל לשלוח אל LinkedIn API.
לקבל https://api.linkedin.com/v2/{service}/1234והנה תגובה לדוגמה שהיא יכולה להחזיר:
{
"מזהה": 1234,
"relatedEntity": "urn: li: relatedEntity: 6789"
}5. פרמטרים וכותרות
עליך גם לתעד את הפרמטרים של נקודות הקצה שלך, שהם אפשרויות שאתה יכול להעביר אליהם. פרמטרים יכולים להיות מזהה או מספר המציינים את כמות או סוג הנתונים המוחזרים בתגובה.
ישנם סוגים שונים של פרמטרים, כולל פרמטרים של כותרת, נתיב ופרמטרים של מחרוזת שאילתה. נקודות הקצה יכולות להכיל סוגים שונים של פרמטרים.
אתה יכול לכלול כמה פרמטרים ככותרות בקשת HTTP. בדרך כלל, אלה הם למטרות אימות כמו מפתח API. הנה דוגמה לכותרת עם מפתחות API:
כותרות: {
'X-RapidAPI-Key': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}
אתה כולל פרמטרים של נתיב בגוף נקודת הקצה ישירות על כתובת האתר. הם מראים למשתמש כיצד והיכן למקם את הפרמטרים וכיצד תופיע התגובה. המילים בסוגרים מתולתלים הן פרמטרים.
אתה יכול גם להשתמש בנקודתיים או תחביר אחר כדי לייצג פרמטרים של נתיב.
/service/myresource/user/{user}/bicycles/{bicycleId}עם פרמטרי שאילתה, עליך להציב סימן שאלה (?) לפני השאילתה בנקודת קצה. הפרד כל פרמטר לאחר מכן באמצעות אמפרסנד (&). למיקרוסופט יש תיעוד טוב על Graph API.
6. קודי שגיאות וטיפול בשגיאות
לפעמים בקשות HTTP נכשלות, מה שעלול להשאיר משתמש מבולבל. כלול קודי שגיאה צפויים בתיעוד כדי לעזור למשתמשים להבין את השגיאות.
LinkedIn מספקת קודי שגיאה סטנדרטיים של HTTP לטיפול בשגיאות:
7. קטעי קוד לדוגמה
קטעי קוד הם חלקים חיוניים בתיעוד שלך. הם מראים למשתמשים כיצד לשלב את ה-API בשפות ובפורמטים שונים. כלול בתיעוד כיצד להתקין ולשלב SDK (ערכות פיתוח תוכנה) בשפות שונות.
ל-RapidAPI יש דוגמאות טובות של קטעי קוד למפתחים:
9. גירסאות API ויומני שינויים
גירסאות API הוא חלק חיוני של עיצוב API. זה מבטיח אספקת שירותים ללא הפרעה למשתמשים שלך. גירסאות יכולות לשפר את ה-API עם גרסאות חדשות מבלי להשפיע על יישומי הלקוח.
משתמשים יכולים להמשיך להשתמש בגרסאות ישנות יותר או לעבור לגרסאות מתקדמות בזמן. אם יש שינויים חדשים ביומנים, כלול אותם בתיעוד כדי שהמשתמשים יהיו מודעים.
ל-Microsoft Graph API יש יומני שינויים מתועדים היטב:
לבסוף, כלול אנשי קשר חשובים בתיעוד לתמיכה ומשוב. אלה מבטיחים שמשתמשים יכולים להגיע אליך עם דוחות שגיאה ומידע על איך לשפר את ה-API.
הערך של תיעוד API
אם אתה בונה API לערך מסחרי, הצריכה קובעת את הצלחתו. וכדי שמשתמשים יוכלו לצרוך את ה-API שלך, הם חייבים להבין אותו.
תיעוד מביא לחיים ממשק API. הוא מסביר את הרכיבים בפירוט בשפה פשוטה שמוכרת את הערך והשימוש בו למשתמשים. משתמשים יצרכו בשמחה את ה-API שלך אם יש להם חווית מפתח נהדרת.
תיעוד טוב גם עוזר לפשט את התחזוקה והקנה מידה של ה-API. צוותים העובדים עם ה-API יכולים להשתמש בתיעוד כדי לנהל אותו.
