API-First: בניית מערכות שמדברות ביניהן

למה API-First ולא "API אחר כך"

רוב המערכות שאנחנו רואים נבנות בגישת code-first: כותבים את ה-backend, ואז חושפים endpoint-ים. זה עובד – עד שמישהו אחר צריך להתחבר למערכת. ואז מתחיל הכאב.

API שנבנה כ-afterthought נראה ככה: שמות endpoint-ים לא עקביים, response formats שמשתנים בין routes, authentication שעובד אחרת בכל מקום, ו-documentation שלא קיים או לא מעודכן. כל מי שניסה להתממשק למערכת ERP ישראלית ותיקה יודע בדיוק על מה אנחנו מדברים.

בגישת API-first, ה-API הוא המוצר. קודם מעצבים את החוזה – ה-contract – ורק אחר כך כותבים קוד. זה אומר:

• Frontend ו-backend יכולים לעבוד במקביל מיום 1
• צוותים אחרים (או לקוחות) יודעים בדיוק מה לצפות לפני ששורה אחת של קוד נכתבת
• ה-API עקבי, מתועד, ו-testable
• אינטגרציות עם צד שלישי הרבה יותר פשוטות

REST vs GraphQL vs gRPC: מתי מה

אין פרוטוקול אחד שמתאים לכל דבר. הנה מתי להשתמש בכל אחד – בלי הייפ, עם דעות.

REST: ברירת המחדל (ובצדק)

שני שלישים מהצוותים עדיין משתמשים ב-REST ל-public endpoints. ויש סיבה טובה: REST פשוט, מוכר לכולם, ו-HTTP caching עובד out of the box.

תשתמשו ב-REST כש:

• בונים public API שצד שלישי יצרוך
• ה-resources מוגדרים היטב (users, orders, products)
• אתם צריכים caching ברמת HTTP
• הלקוחות שלכם מגוונים (mobile, web, IoT, partners)

טיפים ל-REST טוב ב-2026:

• JSON:API או HAL לתשובות עקביות
• Pagination עם cursor-based, לא offset (לא סוקלים)
• HATEOAS אם ה-API ציבורי ומורכב, skip אם פנימי
• Rate limiting headers תמיד (X-RateLimit-Limit, X-RateLimit-Remaining)

GraphQL: כשה-Frontend שולט

בסביבות 40% מהצוותים מטמיעים GraphQL לפיצ'רים חדשים. זה לא מחליף REST – זה משלים אותו.

תשתמשו ב-GraphQL כש:

• ה-frontend צריך flexibility בשאילתות – כל מסך צריך data שונה
• יש בעיות over-fetching או under-fetching עם REST
• בונים dashboard מורכב עם הרבה data sources
• יש צוותי frontend שונים (web, mobile) שצריכים data אחר מאותו backend

מה לא לעשות עם GraphQL:

• לא להשתמש בזה ל-file uploads (REST עדיין טוב יותר)
• לא לחשוף GraphQL ישירות ל-public בלי rate limiting ו-query depth limits – זה מתכון ל-DDoS
• לא להתחיל עם Apollo Federation אם יש לכם שירות אחד – זה overkill

Pattern שעובד: REST ל-public API, GraphQL ל-internal consumption. BFF (Backend for Frontend) שמתרגם בין השניים.

gRPC: כשמילישניות חשובות

כרבע מהצוותים משתמשים ב-gRPC, בעיקר לתקשורת פנימית בין שירותים. Protocol Buffers + HTTP/2 = ביצועים מעולים.

תשתמשו ב-gRPC כש:

• תקשורת פנימית בין microservices
• streaming דו-כיווני (real-time feeds, live updates)
• ביצועים קריטיים – gRPC מהיר פי 5-10 מ-REST + JSON
• polyglot environment – ה-protobuf definitions מייצרים קוד לכל שפה

למה לא gRPC לכל דבר: browsers לא תומכים ב-gRPC ישירות (צריך gRPC-Web), debugging קשה יותר מ-REST (binary protocol), ו-tooling פחות בוגר.

Authentication: לעשות את זה נכון (פעם אחת)

אבטחת API היא לא nice-to-have. זה הדבר הראשון ש-penetration tester בודק. הנה מה שצריך:

OAuth 2.0 + OIDC

הסטנדרט לאימות משתמשים. השתמשו ב-PKCE flow (לא implicit – הוא deprecated). אל תממשו בעצמכם – תשתמשו ב-Auth0, Clerk, או Keycloak.

API Keys

לשימוש server-to-server פשוט. כללים:

• תמיד ב-header (Authorization), אף פעם ב-URL
• rotation policy – החלפה כל 90 יום
• scopes מוגדרים – לא "God key" שעושה הכל
• rate limiting per-key

Rate Limiting

חובה. אין ויכוח. הנה מה שמומלץ:

• Token bucket או sliding window algorithm
• תגדירו limits ברורים: 100 requests/minute ל-free tier, 1000 ל-paid
• תחזירו 429 Too Many Requests עם Retry-After header
• שקלו rate limiting per-endpoint – endpoint של search צריך limit שונה מ-CRUD

Versioning: האמנות של לא לשבור לקוחות

API versioning הוא נושא שגורם לויכוחים אינסופיים. הנה הגישה הפרגמטית:

URL versioning (/v1/, /v2/)

הכי פשוט, הכי ברור, הכי קל ל-routing. כן, זה לא "RESTful pure". לא אכפת לנו. זה עובד.

Header versioning (Accept: application/vnd.api.v2+json)

יותר "נקי" מבחינת REST purists. פחות אינטואיטיבי למפתחים שצורכים את ה-API. תבחרו את זה אם ה-API שלכם ציבורי ואתם רוצים להיראות professional.

הכלל: לא לשבור backwards compatibility

גרסה חדשה רק כשיש breaking change אמיתי. הוספת field? לא breaking. שינוי שם field? breaking. הסרת field? breaking. שינוי type? breaking.

שמרו על גרסה ישנה לפחות 6 חודשים אחרי שיצאה גרסה חדשה. תנו deprecation warnings ב-headers.

OpenAPI/Swagger: איך לעשות את זה נכון

OpenAPI spec (Swagger) הוא הסטנדרט לתיעוד REST APIs. אבל יש הבדל ענק בין OpenAPI שנוצר כ-afterthought לבין OpenAPI שהוא ה-source of truth.

הגישה הנכונה: Design-First

1. כתבו את ה-spec לפני הקוד – ב-YAML, עם Stoplight Studio או Swagger Editor
2. Review ה-spec עם ה-frontend team – הם הלקוחות שלכם. הם צריכים לאשר
3. ייצרו server stubs ו-client SDKs מה-spec – openapi-generator עושה את זה
4. כתבו contract tests – שמוודאים שה-implementation תואם ל-spec
5. CI שמוודא שה-spec מעודכן – אם ה-code חורג מה-spec, ה-build נכשל

טעויות נפוצות:

• Spec שנוצר אוטומטית מה-code ואף פעם לא נבדק – descriptions ריקים, examples חסרים
• Swagger UI בלי authentication – כל אחד יכול לראות את כל ה-endpoints שלכם
• אין examples לכל response – המפתח צריך לנחש מה חוזר
• enum values לא מתועדים – "status can be 1, 2, or 3" בלי להסביר מה כל אחד אומר

Performance: מה שהורג אתכם בפרודקשן

API performance הוא לא רק זמן תגובה. זה throughput, reliability, ו-cost per request.

דברים שעושים הבדל אמיתי:

• Pagination נכון – cursor-based, לא offset. עם dataset של מיליון רשומות, OFFSET 999000 הורג אתכם.
• Compression – gzip לכל response מעל 1KB. חוסך 60-80% bandwidth.
• Connection pooling – לא פותחים DB connection לכל request. Pool של 20-50 connections בדרך כלל מספיק.
• Caching strategy – ETag headers, Cache-Control, ו-Redis לתוצאות שלא משתנות הרבה. API call שחוסכים = כסף.
• N+1 queries – הבעיה הכי נפוצה ב-API performance. תשתמשו ב-DataLoader pattern (ל-GraphQL) או eager loading (ל-REST).

אינטגרציות בשטח: Priority ERP, SAP, ומערכות ישראליות

תיאוריה זה יפה, אבל בשטח הישראלי, API integration זה מלחמה. הנה מה שלמדנו מפרויקטים אמיתיים:

Priority ERP

Priority חשפה REST API סביר ב-versions האחרונים, אבל יש gotchas:

• ה-API לא תמיד מכסה את כל מה שאפשר לעשות ב-UI
• יש procedures שצריך להפעיל דרך ODATA interface ספציפי
• Rate limiting לא מתועד – תגלו אותו ב-production
• תמיד תבנו middleware layer ביניהם – אל תחברו ישירות מה-frontend

SAP

SAP יש לה APIs רבים – אבל המורכבות נמצאת ב-business logic. RFC calls, BAPI, OData services, ו-IDoc – כל אחד מתאים ל-use case אחר.

• ל-real-time data: OData services
• ל-batch operations: IDocs או BAPIs
• SAP Integration Suite (לשעבר CPI) – שווה לשקול כ-middleware
• אל תנסו להתחבר ישירות ל-HANA DB. רצינו.

Pattern שעובד: Integration Layer

הגישה שעובדת הכי טוב: בנו שכבת אינטגרציה ביניים. הלקוחות שלכם (frontend, mobile, partners) מדברים עם ה-API שלכם. ה-API שלכם מדבר עם ה-ERP, ה-CRM, ו-whatever else.

למה? כי כש-Priority ישנה את ה-API שלהם (ויקרה), אתם משנים מקום אחד. לא 15 מקומות שונים שמדברים ישירות עם Priority.

tRPC ו-Type Safety: הטרנד ששווה לעקוב אחריו

אם ה-frontend וה-backend שלכם שניהם TypeScript, tRPC שווה בדיקה רצינית. במקום לכתוב REST endpoints עם OpenAPI spec נפרד, tRPC נותן type safety מקצה לקצה. המפתח בצד הלקוח יודע בדיוק מה ה-API מחזיר – בלי code generation, בלי spec files.

Zod לvalidation, tRPC ל-transport, TypeScript ל-types. שלושה כלים שביחד יוצרים APIs שקשה לטעות בהם.

ההגבלה: רק TypeScript. אם יש לכם Python backend או mobile clients ב-native, tRPC לא רלוונטי.

סיכום: API כמוצר

API טוב הוא לא endpoint שעובד. API טוב הוא מוצר שמפתחים רוצים להשתמש בו. הוא מתועד, עקבי, מאובטח, ו-performant. הוא לא שובר backwards compatibility בלי הודעה. הוא מחזיר שגיאות שאפשר להבין ולטפל בהן.

ב-2026, כל מערכת שלא בנויה API-first היא מערכת שתצטרכו לשכתב כשתרצו להתחבר למערכת אחרת, לפתוח mobile app, או לתת ל-partner גישה. ועל זה חבל לבזבז זמן וכסף.