streamalism.org

מאמר זה הוא חלק מסדרה: • מבוא ל- RAML - שפת הדוגמנות RESTful API (מאמר נוכחי) • ביטול יתירות ב- RAML עם סוגי משאבים ותכונות

• RAML מודולרי באמצעות כולל, ספריות, שכבות-על והרחבות

• הגדר מאפייני RAML מותאמים אישית באמצעות הערות

1. סקירה כללית

במאמר זה אנו מציגים את שפת הדוגמנות RESTful API (RAML), שפת מפרט פתוח ניטראלית של ספק, הבנויה על YAML 1.2 ו- JSON לתיאור ממשקי API של RESTful.

אנו נסקור תחביר בסיסי של RAML 1.0 ומבנה קבצים כאשר אנו מדגימים כיצד להגדיר ממשק API פשוט מבוסס JSON. אנו נראה גם כיצד לפשט את תחזוקת קבצי RAML באמצעות כולל. ואם יש לך ממשקי API מדור קודם המשתמשים בסכמת JSON, נראה כיצד ניתן לשלב סכמות ב- RAML.

לאחר מכן נציג קומץ כלים שיכולים לשפר את המסע שלך ל- RAML, כולל כלי מחבר, מחוללי תיעוד ואחרים.

לבסוף, נסכם על ידי תיאור המצב הנוכחי של מפרט ה- RAML.

2. הגדרת ה- API שלך (יצירת ה- .raml קוֹבֶץ)

ה- API שנגדיר הוא פשוט למדי: בהתחשב בסוגי היישויות פו, להגדיר פעולות בסיסיות של CRUD וכמה פעולות שאילתה. להלן המשאבים שנגדיר עבור ה- API שלנו:

• GET / api / v1 / foos
• POST / api / v1 / foos
• GET / api / v1 / foos / {id}
• PUT / api / v1 / foos / {id}
• מחק / api / v1 / foos / {id}
• GET / api / v1 / foos / name / {name}
• GET / api / v1 / foos? Name = {name} & ownerName = {ownerName}

ובואו נגדיר את ה- API שלנו כחסר מדינה, תוך שימוש באימות HTTP בסיסי, וימסור מוצפן באמצעות HTTPS. לבסוף, בואו לבחור ב- JSON לפורמט העברת הנתונים שלנו (תומך גם ב- XML).

2.1. הגדרות ברמת שורש

נתחיל ביצירת קובץ טקסט פשוט בשם api.raml (ה .raml קידומת מומלצת; השם שרירותי) והוסף את כותרת גרסת RAML בשורה אחת. ברמת הבסיס של הקובץ, אנו מגדירים הגדרות החלות על ה- API כולו:

#% RAML 1.0 כותרת: Baeldung Foo REST Services API באמצעות גרסת סוגי נתונים: פרוטוקולי v1: [HTTPS] baseUri: //myapi.mysite.com/api/{version} mediaType: application / json 

שימו לב בשורה 3 לשימוש בסוגרים {} סביב המילה “גִרְסָה". כך אנו אומרים ל- RAML כי "גִרְסָה" מתייחס לנכס ויש להרחיב אותו. לכן בפועל baseUri יהיה: //myapi.mysite.com/v1

[הערה: ה- גִרְסָה הנכס הוא אופציונלי ולא צריך להיות חלק מה- baseUri.]

2.2. בִּטָחוֹן

אבטחה מוגדרת גם ברמת השורש של .raml קוֹבֶץ. אז בואו נוסיף את הגדרת ערכת האבטחה הבסיסית של HTTP:

אבטחה סכימות: basicAuth: תיאור: כל בקשה חייבת להכיל כותרות הדרושות לסוג אימות בסיסי: אימות בסיסי המתואר מאת: כותרות: הרשאה: תיאור: משמש כדי לשלוח את אישורי "שם המשתמש: הסיסמה" המקודד ל- Base64 סוג: תגובות מחרוזת: 401: תיאור: | לא מורשה. או שילוב שם המשתמש והסיסמה שסופק אינו חוקי, או שהמשתמש אינו רשאי לגשת לתוכן המסופק על ידי כתובת האתר המבוקשת.

2.3. סוגי מידע

לאחר מכן נגדיר את סוגי הנתונים שבהם ה- API שלנו ישתמש:

סוגים: Foo: סוג: מאפייני אובייקט: id: חובה: true סוג: שם שלם: חובה: true סוג: בעל מחרוזת שם: חובה: false סוג: מחרוזת

הדוגמה שלעיל משתמשת בתחביר מורחב להגדרת סוגי הנתונים שלנו. RAML מספק כמה קיצורי דרך תחביריים כדי להפוך את הגדרות הסוג שלנו לפחות מילוליות. להלן קטע סוגי הנתונים המקבילים המשתמש בקיצורי הדרך הבאים:

סוגים: Foo: מאפיינים: id: שם שלם: בעל מחרוזת שם ?: מחרוזת שגיאה: מאפיינים: קוד: הודעה שלמה: מחרוזת

ה '?' תו בעקבות שם נכס מצהיר כי הנכס אינו נדרש.

2.4. אֶמְצָעִי

כעת נגדיר את המשאב ברמה העליונה (URI) של ה- API שלנו:

/ foos:

2.5. פרמטרים של URI

לאחר מכן נרחיב את רשימת המשאבים ונבנה מהמשאב ברמה העליונה שלנו:

/ foos: / {id}: / name / {name}: 

כאן, הסוגריים {} סביב שמות המאפיינים מגדירים פרמטרים של URI. הם מייצגים מצייני מיקום בכל URI ואינם מתייחסים למאפייני קובץ RAML ברמת השורש כפי שראינו לעיל ב- baseUri הַצהָרָה. השורות שנוספו מייצגות את המשאבים / foos / {id} ו / foos / name / {name}.

2.6. שיטות

השלב הבא הוא הגדרת שיטות ה- HTTP החלות על כל משאב:

/ foos: get: post: / {id}: get: put: delete: / name / {name}: get:

2.7. פרמטרי שאילתה

כעת נגדיר דרך לשאילתת ה- foos אוסף באמצעות פרמטרים של שאילתה. שים לב שפרמטרים של שאילתות מוגדרים באמצעות אותו תחביר בו השתמשנו לעיל עבור סוגי נתונים:

/ foos: get: תיאור: ציין את כל קריטריוני השאילתה התואמים את Foos, אם ניתן; אחרת רשום את כל שאילתת FoosParameters: שם ?: מחרוזת בעל שם ?: מחרוזת

2.8. תגובות

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

ניתן להשתמש בסכימת JSON במקום בסוגי נתונים לצורך תאימות לאחור עם גרסה קודמת של RAML. נציג את סכמת JSON בסעיף 3.

[הערה: בקטעי הקוד שלמטה, שורה המכילה שלוש נקודות בלבד (...) מציינת כי חלק מהשורות מדלגות לקצר.]

נתחיל בפעולת ה- GET הפשוטה / foos / {id}:

/ foos: ... / {id}: get: תיאור: קבל Foo לפי תגובות מזהה: 200: body: application / json: type: Foo example: {"id": 1, "name": "Foo First" } 

דוגמה זו מראה כי על ידי ביצוע בקשת GET על המשאב / foos / {id}, עלינו להחזיר את ההתאמה פו בצורה של אובייקט JSON וקוד מצב HTTP של 200.

כך הגדרנו את בקשת ה- GET ב- / foos מַשׁאָב:

/ foos: get: תיאור: ציין את כל קריטריוני השאילתה התואמים את Foos, אם ניתן; אחרת רשום את כל שאילתת FoosParameters: שם ?: מחרוזת בעל שם ?: תגובות מחרוזת: 200: גוף: יישום / json: סוג: Foo [] דוגמה: | [{"id": 1, "name": "First Foo"}, {"id": 2, "name": "Foo Second"}] 

שימו לב לשימוש בסוגריים מרובעים [] המצורפים ל- פו סוּג. זה מדגים כיצד נגדיר גוף תגובה המכיל מערך של פו אובייקטים, כאשר הדוגמה היא מערך של אובייקטים JSON.

2.9. גוף בקשה

לאחר מכן נגדיר את גופי הבקשה המתאימים לכל בקשת POST ו- PUT. נתחיל ביצירת חדש פו לְהִתְנַגֵד:

/ foos: ... פוסט: תיאור: צור גוף Foo חדש: יישום / json: סוג: דוגמה Foo: {"id": 5, "name": "עוד foo"} תגובות: 201: body: application / json : type: Foo דוגמה: {"id": 5, "name": "Foo אחר"} 

2.10. קודי סטטוס

שימו לב בדוגמה שלעיל כי בעת יצירת אובייקט חדש, אנו מחזירים סטטוס HTTP של 201. פעולת PUT לעדכון אובייקט תחזיר מצב HTTP של 200, תוך שימוש באותם גופי בקשה ותגובה כמו פעולת POST.

בנוסף לתגובות ולקודי הסטטוס הצפויים שאנו מחזירים כאשר בקשה מצליחה, אנו יכולים להגדיר את סוג התגובה וקוד המצב שצפוי לו כאשר מתרחשת שגיאה.

בואו נראה כיצד נגדיר את התגובה הצפויה לבקשת GET ב- / foos / {id} משאב כאשר לא נמצא שום משאב עם המזהה הנתון:

 404: body: application / json: type: דוגמה לשגיאה: {"message": "לא נמצא", "code": 1001} 

3. RAML עם סכמת JSON

לפני סוגי מידע הוצגו ב- RAML 1.0, אובייקטים, גופי בקשה וגופי תגובה הוגדרו באמצעות JSON Schema.

באמצעות סוגי מידע יכול להיות חזק מאוד, אך ישנם מקרים שבהם אתה עדיין רוצה להשתמש בסכימת JSON. ב- RAML 0.8 הגדרת את הסכימות שלך באמצעות רמת השורש סכימות סָעִיף.

זה עדיין תקף, אך מומלץ להשתמש ב- סוגים סעיף במקום זאת מאז השימוש ב- סכימות ייתכן שיוצא משימוש בגרסה עתידית. שניהם סוגים ו סכימות, בנוסף ל סוּג ו סכֵימָה, הם שם נרדף.

כך תגדיר את סוג האובייקט Foo ברמת השורש של ה- .raml קובץ באמצעות סכימת JSON:

סוגים: foo: | {"$ schema": "//json-schema.org/schema", "type": "object", "description": "Foo details", "properties": {"id": {"type": integer }, "name": {"type": "string"}, "ownerName": {"type": "string"}}, "חובה": ["id", "name"]}

וכאן היית מתייחס לסכמה ב- GET / foos / {id} הגדרת משאבים:

/ foos: ... / {id}: get: תיאור: קבל Foo לפי התגובות שלו מזהה: 200: body: application / json: type: foo ...

4. Refactoring עם כולל

כפי שניתן לראות מהסעיפים לעיל, ה- API שלנו נהיה די מילולי וחוזר על עצמו.

מפרט ה- RAML מספק מנגנון כולל המאפשר לנו להחצין קטעי קוד חוזרים וארוכים.

אנו יכולים לשקף מחדש את הגדרת ה- API שלנו באמצעות כולל, מה שהופך אותה לתמציתית יותר ופחות להכיל את סוגי השגיאות הנובעות ממתודולוגיית "העתק / הדבק / תקן בכל מקום".

לדוגמה, אנו יכולים לשים את סוג הנתונים עבור a פו אובייקט בקובץ סוגים / Foo.raml והסוג ל- שְׁגִיאָה חפץ ב סוגים / Error.raml. ואז שלנו סוגים החלק ייראה כך:

types: Foo:! include types / Foo.raml Error:! include types / Error.raml

ואם אנו משתמשים בסכמת JSON במקום זאת, שלנו סוגים החלק עשוי להיראות כך:

types: foo:! include schemas / foo.json error:! include schemas / error.json

5. השלמת ה- API

לאחר החצנת כל סוגי הנתונים והדוגמאות לקבצים שלהם, אנו יכולים לשקול מחדש את ה- API שלנו באמצעות מתקן הכלול:

#% RAML 1.0 כותרת: גרסת API של Baeldung Foo REST Services: פרוטוקולי v1: [HTTPS] baseUri: //rest-api.baeldung.com/api/{version} mediaType: יישום / json מאובטח מאת: basicAuth securitySchemes: basicAuth: תיאור: כל בקשה חייבת להכיל את הכותרות הדרושות לסוג האימות הבסיסי: אימות בסיסי המתואר מאת: כותרות: הרשאה: תיאור: משמש לשליחת בסיס האישורים המקודד "שם משתמש: סיסמה" מסוג Base64: מחרוזת תגובות: 401: תיאור: | לא מורשה. או שילוב שם המשתמש והסיסמה שסופק אינו חוקי, או שהמשתמש אינו רשאי לגשת לתוכן המסופק על ידי כתובת האתר המבוקשת. types: Foo:! include types / Foo.raml Error:! include types / Error.raml / foos: get: תיאור: ציין את כל קריטריוני השאילתה התואמים ל- Foos, אם ניתן; אחרת רשום את כל שאילתת FoosParameters: שם ?: מחרוזת בעל שם ?: תגובות מחרוזת: 200: גוף: יישום / json: סוג: Foo [] דוגמה:! כלול דוגמאות / פוסט.json פוסט: תיאור: צור גוף Foo חדש: יישום / json: סוג: דוגמה Foo:! כלול דוגמאות / תגובות Foo.json: 201: גוף: יישום / json: סוג: דוגמה Foo:! כולל דוגמאות / Foo.json / {id}: קבל: תיאור: קבל Foo לפי מזהה תגובות: 200: גוף: יישום / json: סוג: דוגמה Foo:! כולל דוגמאות / Foo.json 404: גוף: יישום / json: סוג: דוגמה לשגיאה:! כלול דוגמאות / Error.json put: תיאור: עדכן Foo על ידי גוף גוף: יישום / json: סוג: דוגמה Foo:! כולל דוגמאות / תגובות Foo.json: 200: גוף: יישום / json: סוג: דוגמה Foo:! כולל דוגמאות / Foo.json 404: גוף: יישום / json: סוג : דוגמה לשגיאה:! כלול דוגמאות / Error.json delete: תיאור: מחק Foo לפי תגובות מזהה: 204: 404: body: application / json: type: דוגמה לשגיאה:! Include דוגמאות / Error.json / name / {name} : לקבל: תיאור: ציין את כל התגובות עם שם מסוים תגובות: 200: body: application / json: type: Foo [] דוגמה:! Include דוגמאות / Foos.json 

6. כלי RAML

אחד הדברים הנהדרים ב- RAML הוא התמיכה בכלי.

ישנם כלים לניתוח, אימות ועריכת ממשקי API של RAML; כלים לייצור קוד לקוח; כלים ליצירת תיעוד API בפורמטים HTML ו- PDF; וכלים המסייעים לנו בבדיקה על פי מפרט RAML API.

יש אפילו כלי שימיר ממשק API של Swagger JSON ל- RAML.

הנה דוגמה של כלים זמינים:

• API Designer - כלי מבוסס אינטרנט המיועד לתכנון API מהיר ויעיל
• API Workbench - IDE לעיצוב, בנייה, בדיקה ותיעוד ממשקי API RESTful התומכים הן ב- RAML 0.8 והן ב- 1.0
• RAML Cop - כלי לאימות קבצי RAML
• RAML עבור JAX-RS - סט כלים ליצירת שלד של קוד יישום Java + JAX-RS ממפרט RAML, או ליצירת מפרט RAML מיישום JAX-RS קיים.
• תוסף RAML Sublime - תוסף סימון תחביר לעורך הטקסט הנשגב
• RAML ל- HTML - כלי להפקת תיעוד HTML מ- RAML
• raml2pdf - כלי להפקת תיעוד PDF מ- RAML
• RAML2Wiki - כלי להפקת תיעוד Wiki (באמצעות Confluence / JIRA markup)
• תוסף RAML של SoapUI - תוסף RAML לחבילת בדיקות ה- API הפונקציונלית של SoapUI
• ויגיה - חבילת בדיקות אינטגרציה המסוגלת ליצור מקרי בדיקה על סמך הגדרת RAML

לקבלת רשימה מלאה של כלי RAML ופרויקטים נלווים, בקר בדף RAML Projects.

7. המצב הנוכחי של RAML

המפרט של RAML 1.0 (RC) זכה למעמד של מועמד לשחרור ב- 3 בנובמבר 2015, ובמועד כתיבת שורות אלה, גרסה 1.0 צפויה להסתיים סופית בתוך החודש.

קודמתה, RAML 0.8 שוחררה במקור בסתיו 2014 והיא עדיין נתמכת על ידי מספר עצום של כלים.

8. קריאה נוספת

להלן מספר קישורים שנמצא שימושי במהלך המסע שלנו עם RAML.

• RAML.org - האתר הרשמי של מפרט ה- RAML
• json-schema.org - הבית של סכמת JSON
• הבנת סכמת JSON
• מחולל סכמות JSON
• דף RAML בוויקיפדיה

9. מסקנה

מאמר זה הציג את RESTful API Modelling Language (RAML). הדגמנו תחביר בסיסי לכתיבת מפרט API פשוט בעזרת המפרט RAML 1.0 (RC).

וראינו דרכים להפוך את ההגדרות שלנו לתמציתיות יותר על ידי שימוש בקיצורי דרך תחביריים ובדוגמאות החצנה, סוגי נתונים וסכמות לקבצים 'כוללים'.

לאחר מכן הצגנו אוסף של כלים רבי עוצמה שעובדים עם מפרט ה- RAML בכדי לסייע במשימות תכנון, פיתוח, בדיקה ותיעוד יומיומיות של ה- API.

עם המהדורה הרשמית הקרובה של גרסת 1.0 של המפרט, יחד עם התמיכה המוחצת של מפתחי כלים, נראה ש- RAML כאן כדי להישאר.

הַבָּא » ביטול יתירות ב- RAML באמצעות סוגי משאבים ותכונות