דף זה מתאר את ממשק התִּכנוּת (API) של פרויקט בן־יהודה. הוא נועד למי שיודע לתכנת ולצרוך שירותים ממוכנים דרך API רשת רגיל. אם אין זה מתאר אותך, אין טעם להמשיך לקרוא את הדף הזה. :)
בשלב זה, מאפשר ה־API גישה לכל היצירות והמחברים במאגר היצירה של פרויקט בן־יהודה, חיפושים וסינונים פשוטים ומורכבים, והורדת יצירות כקבצים בתבניות שונות.
- ה־API מוצע לכל דכפין מתוך רצון טוב ושאיפה לשרת את הציבור ולעודד עיסוק בחומרי המאגר.
- ה־API דורש מפתח מכל המבקש להשתמש בו. את המפתחות אפשר להנפיק בשירות עצמי, בחינם. המפתחות מונפקים מיידית לכל דכפין ונשלחים בדואל לכתובת שהוזנה.
- יש לכבד את משתמשי האתר האחרים ולהתחשב במשאבינו הצנועים, ולא להמטיר על השרת בקשות בקצב מהיר מדי. אנו מבקשים שלא תשגרו יותר מ־50 בקשות בדקה, לכל היותר. אנא דאגו לכך מראש בתוכנה שאתם מפתחים מול ה־API. אם נראה שימוש לא־מתחשב ב־API מצד משתמש API, נפנה אליו ונבקש שיחדל מכך, ואם לא ניענה, נבטל אותו מפתח שימוש.
לאחר קבלת המפתח (בדואל), תוכלו לבצע פניות ל־API באמצעות בקשות HTTP POST על פי התיעוד. למשל, בעזרת כלי שורת־הפקודה curl, אפשר להריץ:
curl -X POST “https://benyehuda.org/api/v1/search” -H “accept: application/json” -H “Content-Type: application/json” -d “{ "key": "YOUR KEY", "view": "basic", "file_format": "html", "snippet": false, "page": 0, "sort_by": "alphabetical", "sort_dir": "default", "genres": [ "poetry" ]}”
כאשר במקום YOUR KEY יוזן המפתח שנשלח בדואל, כדי לאתר את כל יצירות השירה, ואחר כך גם לדפדף בהן, בעזרת פרמטר העמוד.
לפי שעה יש רק תיעוד אוטומטי נוח ואינטרקטיבי, אמנם באנגלית, דרך חבילת Swagger.
בנוסף לתיעוד מפורט של כל נקודות הכניסה ל־API על הפרמטרים שלהן, הדף הזה כולל גם “ארגז חול” שמאפשר אפילו להריץ קריאות API ממש מתוך התיעוד (בתנאי שתדביקו לתוך ה־JSON את המפתח שהונפק לכם).
נשמח מאוד למשוב על חוויית השימוש בתיעוד הזה.
חידוש משמח במיוחד הוא שה־API מאפשר (והאתר הרגיל עדיין לא!) שילוב של חיפוש טקסט־מלא עם סינון על בסיס מטא־דאטה. כלומר, אפשר לחפש מופעים של מלים או צירופים מסוימים רק בפרוזה מתקופת התחייה, למשל, או רק ביצירות שעלו לפרויקט בשנה האחרונה, או רק בספרות שנכתבה על ידי נשים, או תורגמה מגרמנית, וכן הלאה, או כל שילוב של כל אלה.
אנחנו מקווים שתעשו שימוש ב־API, ושתספרו לנו עליו – גם צרות וגם ישועות :) – בעתיד הקרוב. נשמח לשמוע על כל דבר שבניתם עם ה־API, ולחלוק אותו עם מתנדבינו, שישמחו לראות עוד פירות לעמלם. כתבו אלינו!