REST API לאנשי רשת: המדריך המלא בעברית — HTTP Verbs, קודי סטטוס, JSON ואימות, עם מבחנון CCNA

בעולם שבו Controller מנהל מאות מתגים, אף אחד לא נכנס יותר לכל התקן ב-SSH. הממשק שדרכו תוכנה מדברת עם תוכנה נקרא API, ובעולם הרשתות הסגנון הנפוץ ביותר הוא REST. אם אתם ניגשים למבחן 200-301 או פשוט רוצים להיכנס לעולם האוטומציה — זהו הנושא שאי אפשר לדלג עליו.

מהו API ומה הופך אותו ל-RESTful

API הוא חוזה: הוא מגדיר אילו בקשות אפשר לשלוח לשירות, באיזה פורמט, ומה יוחזר בתגובה. REST, ראשי תיבות של Representational State Transfer, אינו פרוטוקול אלא סגנון ארכיטקטוני שהוגדר בשנת 2000. ממשק נחשב RESTful כשהוא עומד במספר עקרונות מרכזיים.

• ▸Client-Server — הפרדה מלאה בין הלקוח שמבקש לבין השרת שמספק.
• ▸Stateless — השרת אינו שומר הקשר בין בקשות. כל בקשה חייבת להכיל את כל המידע הדרוש, כולל פרטי האימות.
• ▸Cacheable — התגובה מציינת אם ניתן לשמור אותה במטמון.
• ▸Uniform Interface — משאבים מזוהים באמצעות URI ומטופלים בפעולות סטנדרטיות.
• ▸Layered System — ייתכנו שרתי ביניים, Proxy או Load Balancer, והלקוח אינו צריך לדעת עליהם.

פעולות CRUD ושיטות HTTP

REST משתמש בשיטות ה-HTTP הקיימות כדי לבטא פעולות על משאבים. ההתאמה למודל CRUD היא הדבר הראשון שנבדק במבחן.

• ▸GET — קריאה (Read). אינו משנה דבר, ולכן נחשב בטוח ואידמפוטנטי.
• ▸POST — יצירה (Create) של משאב חדש. אינו אידמפוטנטי — שליחה כפולה תיצור שני משאבים.
• ▸PUT — עדכון או החלפה מלאה (Update). אידמפוטנטי — שליחה חוזרת מביאה לאותה תוצאה.
• ▸PATCH — עדכון חלקי של שדות מסוימים בלבד.
• ▸DELETE — מחיקה (Delete) של המשאב.

מבנה ה-URI — לקרוא כתובת כמו מהנדס

כתובת של קריאת API מורכבת מרכיבים קבועים, וכדאי לדעת לזהות כל אחד מהם: הסכימה (https), שם המארח (dnac.netme.local), נתיב הבסיס עם גרסה (‎/dna/intent/api/v1‎), המשאב (‎/network-device‎), מזהה ספציפי (‎/12345‎) ופרמטרים אחרי סימן השאלה (‎?limit=50&offset=0‎). שימוש בגרסה בנתיב הוא תרגול חובה — הוא מאפשר לשנות את ה-API בעתיד בלי לשבור לקוחות קיימים.

קודי תגובה שחייבים לזכור

• ▸200 OK — הבקשה הצליחה והתשובה מצורפת.
• ▸201 Created — משאב חדש נוצר בהצלחה, בדרך כלל בתגובה ל-POST.
• ▸204 No Content — הפעולה הצליחה ואין גוף תגובה, נפוץ ב-DELETE.
• ▸400 Bad Request — הבקשה שגויה תחבירית או שחסר בה שדה חובה.
• ▸401 Unauthorized — לא בוצע אימות או שהטוקן פג תוקף.
• ▸403 Forbidden — האימות תקין אך אין הרשאה לפעולה.
• ▸404 Not Found — המשאב אינו קיים בכתובת שנשלחה.
• ▸429 Too Many Requests — חריגה ממגבלת קצב הקריאות (Rate Limit).
• ▸500 Internal Server Error — תקלה בצד השרת, לא בבקשה שלכם.

כלל זהב לפתרון תקלות: 4xx אומר שהבעיה אצלכם, 5xx אומר שהבעיה אצל השרת. ההבחנה הזו חוסכת שעות של חיפוש במקום הלא נכון.

JSON — שפת הנתונים של האוטומציה

רוב ממשקי ה-REST בעולם הרשתות מחזירים JSON. המבנה שלו פשוט: סוגריים מסולסלים מגדירים אובייקט של זוגות מפתח-ערך, סוגריים מרובעים מגדירים מערך, ומפתחות תמיד עטופים במרכאות כפולות. ב-Python אובייקט הופך ל-dictionary ומערך הופך ל-list, וההמרה מתבצעת בעזרת json.loads לקריאה ו-json.dumps לכתיבה.

import requests, json

BASE = "https://dnac.netme.local/dna"

# 1. Authenticate and receive a token
auth = requests.post(f"{BASE}/system/api/v1/auth/token",
                     auth=("netme_api", "S3cure!Pass"), verify=True)
token = auth.json()["Token"]

# 2. Use the token on every subsequent request (REST is stateless)
headers = {"X-Auth-Token": token, "Content-Type": "application/json"}

r = requests.get(f"{BASE}/intent/api/v1/network-device",
                 headers=headers, params={"limit": 3})

print(r.status_code)          # 200
for dev in r.json()["response"]:
    print(dev["hostname"], dev["managementIpAddress"], dev["softwareVersion"])

{
  "response": [
    {
      "hostname": "NETME-CORE-SW1",
      "managementIpAddress": "10.10.0.11",
      "platformId": "C9300-48U",
      "softwareVersion": "17.12.3",
      "reachabilityStatus": "Reachable",
      "interfaces": ["Gi1/0/1", "Gi1/0/2", "Te1/1/1"]
    }
  ],
  "version": "1.0"
}

אימות ואבטחה

• ▸Basic Authentication — שם משתמש וסיסמה מקודדים ב-Base64. קידוד אינו הצפנה, ולכן חובה HTTPS.
• ▸API Key — מפתח קבוע בכותרת. פשוט ליישום, אך קשה לביטול סלקטיבי ולסבב מפתחות.
• ▸Bearer Token או OAuth 2.0 — טוקן זמני עם תוקף מוגבל. השיטה המומלצת בסביבות ייצור.
• ▸לעולם אל תשמרו סיסמאות או טוקנים בתוך הקוד — השתמשו במשתני סביבה או בכספת סודות.
• ▸אכפו TLS ובדקו את תעודת השרת. ביטול אימות התעודה בסקריפט הוא פתח למתקפת Man-in-the-Middle.

REST מול פרוטוקולי ניהול אחרים

לצד REST קיימים בעולם הרשתות גם NETCONF ו-RESTCONF. NETCONF עובד מעל SSH בפורט 830, משתמש ב-XML ומבוסס על מודלי YANG, ומספק יכולות חזקות כמו Candidate Configuration ו-Commit אטומי. RESTCONF הוא גשר בין העולמות: ממשק בסגנון REST מעל HTTPS שמשתמש גם הוא במודלי YANG ותומך ב-JSON וב-XML. SNMP, לעומתם, נשאר בעיקר לניטור ולא לתצורה.

לסיכום

REST API הוא שער הכניסה לעולם האוטומציה. ברגע שאתם יודעים לקרוא URI, לבחור Verb נכון, להבין קוד תגובה ולפרק JSON — אתם כבר לא רק מתפעלים רשת, אתם מתכנתים אותה. זו בדיוק ההבחנה שמעלה שכר בשוק היום.

בקורס CCNA של מכללת נטמי מתרגלים את הנושא במעבדות אמיתיות: שליפת מידע מ-Controller, כתיבת סקריפט Python ראשון, טיפול בשגיאות והבנת ההבדל בין REST, RESTCONF ו-NETCONF — הכול בעברית, צעד אחר צעד, עד למבחן 200-301.