תוכן עניינים:
- עשה את שיעורי הבית שלך
- היה עקבי
- השתמש ב- OAuth
- להתחיל מוקדם
- כתוב תיעוד טוב
- פיתוח API: שמור על זה פשוט
זה אופי פיתוח תוכנה. מפתחים יוצרים תוכנה כשמשתמש קצה בחשבון. זה נראה די פשוט, אבל לפעמים המשתמשים האלה הם גם מפתחים עמיתים אחרים. הם לא זקוקים לדברים המפורקים בשבילם. הם אפילו לא צריכים אפילו את הפשטות. כל מה שהם רוצים זה גישה - דרך לשלב את התוכנה שלך עם שלהם. כאן נכנס ממשק API (ממשק תכנות יישומים). אני מקווה להדגיש חמישה צעדים שתוכלו לנקוט כדי ליצור API מצליח.
עשה את שיעורי הבית שלך
כשמדובר בפיתוח תוכנה, אף אחד מאיתנו לא רוצה להמציא את הגלגל מחדש. בשלב זה כמעט לכל חברות האינטרנט הגדולות יש ממשקי API למוצרי התוכנה שלהם. חקר ממשקי API אלה ונסה להבחין בהחלטות העיצוב השונות שהתחילו ליצור אותם.
יש הרבה טכנולוגיות שונות שם, אבל רוב ממשקי ה- API שתראו עומדים להשתמש בממשק RESTful או ב- SOAP. אם אתה על הגדר באיזה ממשק API אתה מתכוון להשתמש, הייתי מציע ללכת עם גישה RESTful באמצעות פרוטוקול HTTP. זה פשוט יותר מ- SOAP, הוא כרגע פופולרי יותר, ויהיה קל יותר להתחיל לעבוד עם מוצר תוכנה מבוסס אינטרנט.
היה עקבי
אחד הדברים שהמפתחים מעריכים ביותר הוא עקביות. זה כולל בין היתר את הניתנות להתייחסות, טיעוני קלט, פורמטי פלט וטיפול בשגיאות.
בעת שימוש בגישה RESTful, ישנן הרבה תכניות שמות שונות של URI. לכל אחד יש את התומכים שלו, אז פשוט בחרו אחד והיצמדו אליו. כך גם במבנה הקלט והפלט. רוב ה- API תומכים בשימוש ב- XML ו- JSON כפורמט קלט ופלט. הייתי מציע לתמוך בשניהם, אך לבחור בפורמט ברירת מחדל.
לצורך הקלט, יש לציין באופן עקבי את דרישות הקלט שלך וצריכים להיות הגיוניים בהקשר של שיחת ה- API שאתה מבצע. לפלט, וודא שאתה משתמש בפריסות מבנה נתונים נפוצות. אם אתה עורך את הפלט של שיחת API אחת ב-
מקובל לכלול איזשהו דגל סטטוס בנתוני הפלט שאתה שולח חזרה ללקוח. בעת שימוש בגישת ממשק RESTful, יש לעשות זאת באמצעות קודי סטטוס HTTP. לדוגמה, אם רק עיבדת בקשת PUT על אובייקט נתונים קיים, קוד מצב HTTP שתכלול בתגובה שלך ישתנה בהתאם לתוצאת הבקשה.
במקום דגל שרירותי המציין את מצב השיחה, ניתן להשתמש בקוד סטטוס "200 אישור" רגיל כדי לסמן שהבקשה הצליחה, ואילו ניתן להשתמש בקוד סטטוס "400 בקשה רעה" כדי לסמן שהבקשה הייתה מעוות. ישנם לא מעט קודי סטטוס HTTP בהם ניתן להשתמש במצבים שונים.
השתמש ב- OAuth
מרבית מוצרי התוכנה כרוכים באימות כלשהו של משתמשים על מנת לגשת למשאבים מוגנים עבור אותו משתמש. כשמדובר בממשקי API, לקיים את הלקוח לאסוף את אישורי המשתמש שישלחו לשרת שלך זה פרקטיקה לא טובה. כאן נכנס OAuth.
OAuth מספק יתרונות רבים על ידי אימות שם משתמש / סיסמא של צד שלישי. מעל לכל, ללקוח מעולם אין גישה לתעודות המשתמש. המשתמש מנותב לשרת שלך כאשר הוא או היא נכנסים. לאחר שהמשתמש נכנס לאתר שלך, הוא או היא מופנים חזרה ללקוח בו הלקוח יקבל אסימון גישה לשימוש בבקשות עתידיות למשאבים מוגנים.
יתרון חשוב נוסף בשימוש ב- OAuth הוא היכולת של המשתמש לבטל את הגישה ללקוח בכל עת. אם המשתמש מחליט שמסיבה כלשהי הוא כבר לא רוצה שהלקוח יוכל לגשת למשאבים מוגנים מטעמו, הוא פשוט עובר לממשק שיצרת וביטל את גישת הלקוח.
להתחיל מוקדם
אחד הדברים החשובים ביותר שאתה יכול לעשות בכדי להפוך את ה- API שלך להצלחה הוא להתחיל מוקדם. כשאתה כותב את הפונקציה הזו ליצירת ערך כלשהו בבסיס הנתונים שלך, קדימה קח את הזמן הנוסף וכתב ממשק API לזה.כתוב תיעוד טוב
שום דבר לא הורג ממשק API מהר יותר מאשר שלא היה לו תיעוד טוב. בעוד שחלק מהמפתחים יכולים לקחת ממשק API שמתועד בצורה לא טובה ולהבין כיצד הוא אמור לעבוד, רובם לא ירצו.
עליך לתעד כל שיחת API שזמינה ולקטלג את שיחות ה- API שלך לפי סוג הנתונים שהם פועלים על פיהם. יחד עם תיעוד נקודות הקצה עבור שיחות ה- API עצמן, עליך להגדיר באופן שיטתי את טיעוני הקלט הנדרשים והאופציונליים, כמו גם את מבני נתוני הפלט. ארגומני קלט צריכים לרשום ערך ברירת מחדל אם יש כזה, ולציין גם את פורמט הנתונים הצפוי כמו מספר או מחרוזת. לבסוף, לכל קריאת API צריכה להיות רשימת תנאי שגיאה וקודי מצב.
כדי לסגור את התיעוד שלך, הקפד לכלול דוגמה אחת או שתיים לתרחישים קלט ופלט נפוצים עבור כל שיחת API.
פיתוח API: שמור על זה פשוט
אמנם נראה כי פיתוח ממשק API הוא מאמץ מסובך, אך הרעיון של ממשק API עצמו אינו מושג חדש ויש כמות גדולה של תיעוד זמין בכל נושא בו נגענו. רק הקפידו להשתמש בשיטות טובות בהן תוכלו למצוא אותם, ולספק ממשק עקבי ומתועד.
