streamalism.org

מאמר זה הוא חלק מסדרה: • מבוא ל- RAML - שפת הדוגמנות RESTful API

• ביטול יתירות ב- RAML באמצעות סוגי ותכונות משאבים (מאמר נוכחי) • RAML מודולרי באמצעות כולל, ספריות, שכבות-על והרחבות

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

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

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

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

2. ה- API שלנו

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

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

3. זיהוי דפוסים

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

בואו נסתכל על כמה קטעים של ה- API שלנו:

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

/ foos: get: תיאור: | ציין את כל foos התואמים את קריטריוני השאילתה, אם צוין; אחרת רשום את כל שאילתת foosParameters: שם ?: בעל מחרוזת שם ?: תגובות מחרוזת: 200: body: application / json: type: Foo [] post: תיאור: צור גוף foo חדש: application / json: type: Foo תגובות: 201: body: application / json: type: Foo ... / bars: get: תיאור: | ציין את כל הסורגים התואמים את קריטריוני השאילתה, אם ניתן; אחרת רשום את כל השורות queryParameters: שם ?: בעל מחרוזת שם ?: תגובות מחרוזת: 200: body: application / json: type: Bar [] post: תיאור: צור body body חדש: application / json: type: Bar תגובות: 201: גוף: יישום / json: סוג: סרגל

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

בכל מקום שיש דפוס בהגדרת משאב או שיטה, קיימת הזדמנות להשתמש ב- RAML סוג משאבים אוֹ תְכוּנָה.

4. סוגי משאבים

על מנת ליישם את הדפוסים שנמצאו ב- API, סוגי משאבים השתמש בפרמטרים שמורים ומוגדרים על ידי המשתמש המוקפים בסוגריים זוויתיים כפולים (<>).

4.1 פרמטרים שמורים

ניתן להשתמש בשני פרמטרים שמורים בהגדרות סוג המשאב:

• <> מייצג את כל ה- URI (בעקבות ה- baseURI), ו
• <> מייצג את החלק של ה- URI שעוקב אחר קו נטוי הימני ביותר (/), תוך התעלמות מכל סוגריים {}.

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

בהתחשב במשאב / foos, לדוגמה, <> יעריך ל "/ foos" ו- <>היה מעריך ל"פוס ".

בהתחשב במשאב / foos / {fooId}, <> יעריך ל- "/ foos / {fooId}" ו- <>היה מעריך ל"פוס ".

4.2 פרמטרים המוגדרים על ידי המשתמש

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

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

4.3 פונקציות פרמטר

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

להלן הפונקציות הזמינות לשינוי פרמטרים:

• !לייחד
• !לרבות
• !אותיות רישיות
• !אותיות קטנות
• !מארז עליון
• !מארז תחתון
• !מקרה הגבול העליון
• !מקרה תחתון נמוך יותר
• !hyperhyphencase
• !נמוכה יותר

פונקציות מוחלות על פרמטר באמצעות המבנה הבא:

<<שם פרמטר | !functionName>>

אם אתה צריך להשתמש ביותר מפונקציה אחת כדי להשיג את השינוי הרצוי, היית מפריד בין כל שם פונקציה עם סמל הצינור ("|") ומקדים סימן קריאה (!) לפני כל פונקציה.

לדוגמא, בהתחשב במשאב / foos, שם <<resourcePathName>> מעריך ל- "foos":

• <<resourcePathName | !לייחד>> ==> "foo"
• <<resourcePathName | !אותיות רישיות>> ==> "FOOS"
• <<resourcePathName | !לייחד | !אותיות רישיות>> ==> "FOO"

ובהתחשב במשאב / סורגים / {barId}, שם <<resourcePathName>> מעריך ל"סורגים ":

• <<resourcePathName | !אותיות רישיות>> ==> "BARS"
• <<resourcePathName | !מארז עליון>> ==> "בר"

5. חילוץ סוג משאבים לאוספים

בואו נשקף את ה- / foos ו / סורגים הגדרות משאבים המוצגות לעיל, תוך שימוש ב- סוג משאבים כדי לתפוס את המאפיינים הנפוצים. נשתמש בפרמטר השמור <>, והפרמטר שהוגדר על ידי המשתמש <> כדי לייצג את סוג הנתונים המשמש.

5.1 הגדרה

הנה א סוג משאבים הגדרה המייצגת אוסף פריטים:

resourceTypes: collection: use: השתמש ב- resourceType זה כדי לייצג כל אוסף של פריטים תיאור: אוסף של <> get: description: קבל את כל <>, תגובות מסוננות אופציונליות: 200: body: application / json: type: <> [] post : תיאור: צור <> תגובות חדשות: 201: גוף: יישום / json: סוג: <>

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

resourceTypes: collection: ... get: ... type: <> [] post: ... type: <>

5.2 יישום

באמצעות ההגדרה לעיל המשלבת את ה <<סוג שם>> פרמטר, כך תיישם את "האוסף" סוג משאבים למשאבים / foos ו /סורגים:

/ foos: type: {collection: {"typeName": "Foo"}} get: queryParameters: name ?: string string name ?: string ... / bars: type: {collection: {"typeName": "Bar"} }

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

6. חילוץ סוג משאבים לפריטים בודדים באוסף

בואו נתמקד כעת בחלק של ה- API שלנו העוסק בפריטים בודדים של אוסף: / foos / {fooId} ו / ברים / {barId} אֶמְצָעִי. הנה הקוד עבור/ foos / {fooId}:

/ foos: ... / {fooId}: get: תיאור: קבל תגובות Foo: 200: body: application / json: type: Foo 404: body: application / json: type: דוגמה לשגיאה:! כלול דוגמאות / שגיאה. json put: תיאור: עדכן גוף Foo: יישום / json: סוג: תגובות Foo: 200: body: application / json: type: Foo 404: body: application / json: type: דוגמה לשגיאה:! include דוגמאות / Error.json מחק: תיאור: מחק תגובות של Foo: 204: 404: גוף: יישום / json: סוג: דוגמה לשגיאה:! כלול דוגמאות / Error.json

ה / ברים / {barId} להגדרת משאבים יש גם שיטות GET, PUT ו- DELETE והיא זהה ל- /foos / {fooId} הגדרה, מלבד המופעים של המיתרים "foo" ו- "bar" (וצורותיהם המרובות ו / או באותיות רישיות שלהם).

6.1 הגדרה

חילוץ הדפוס שזיהינו זה עתה, כך אנו מגדירים a סוג משאבים לפריטים בודדים של אוסף:

resourceTypes: ... item: use: השתמש ב- resourceType זה כדי לייצג כל תיאור פריט בודד: <> get: description: קבל תגובה <>: 200: body: application / json: type: <> 404: body: application / json: סוג: דוגמה לשגיאה:! כלול דוגמאות / Error.json put: תיאור: עדכן <> גוף: יישום / json: סוג: <> תגובות: 200: גוף: יישום / json: סוג: <> 404: גוף : יישום / json: סוג: דוגמה לשגיאה:! כוללים דוגמאות / Error.json מחק: תיאור: מחק תגובות <204: 404: גוף: יישום / json: סוג: דוגמה לשגיאה: כלול דוגמאות / Error.json

6.2 יישום

וכאן אנו מיישמים את ה"פריט " סוג משאבים:

/ foos: ... / {fooId}: type: {item: {"typeName": "Foo"}}

... / bars: ... / {barId}: type: {item: {"typeName": "Bar"}}

7. תכונות

ואילו א סוג משאבים משמש לחילוץ דפוסים מהגדרות משאבים, א תְכוּנָה משמש לחילוץ דפוסים מהגדרות השיטה הנפוצות בין משאבים.

7.1 פרמטרים

יחד עם <<resourcePath>> ו <<resourcePathName>>, פרמטר אחד שמור נוסף זמין לשימוש בהגדרות תכונות: <<methodName>> מעריך לשיטת HTTP (GET, POST, PUT, DELETE, וכו ') עבורה ה- תְכוּנָה מוגדר. פרמטרים המוגדרים על ידי משתמשים עשויים להופיע גם במסגרת הגדרת תכונה, ובמקום שהם מיושמים, מקבלים על עצמם את ערך המשאב בו הם מוחלים.

7.2 הגדרה

שימו לב שה"פריט " סוג משאבים עדיין מלא בפיטורים. בואו נראה איך תכונות יכול לעזור לחסל אותם. נתחיל בחילוץ a תְכוּנָה לכל שיטה המכילה גוף בקשה:

תכונות: hasRequestItem: body: application / json: type: <>

עכשיו בואו נחלץ תכונות לשיטות שהתגובות הרגילות שלהם מכילות גופים:

 hasResponseItem: תגובות: 200: גוף: יישום / json: סוג: <> hasResponseCollection: תגובות: 200: גוף: יישום / json: סוג: <> []

לבסוף, הנה א תְכוּנָה לכל שיטה שיכולה להחזיר תגובת שגיאה 404:

 hasNotFound: תגובות: 404: body: application / json: type: example error:! include דוגמאות / Error.json

7.3 יישום

לאחר מכן אנו מיישמים זאת תְכוּנָה שלנו סוגי משאבים:

resourceTypes: collection: use: השתמש ב- resourceType זה כדי לייצג כל אוסף פריטים תיאור: אוסף של <> get: description: | קבל את כל ה <>, מסונן באופן אופציונלי הוא: [hasResponseCollection: {typeName: <>}] פוסט: תיאור: צור פריט <> is: [hasRequestItem: {typeName: <>}] פריט: שימוש: השתמש במשאב זה סוג לייצג כל אחד תיאור פריט יחיד: <> get: description: Get a <> יחיד הוא: [hasResponseItem: {typeName: <>}, hasNotFound] put: תיאור: עדכן <> is: | [hasRequestItem: {typeName: <>}, hasResponseItem: {typeName: <>}, hasNotFound] delete: תיאור: מחק את <> is: [hasNotFound] תגובות: 204:

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

/ foos: ... / name / {name}: get: תיאור: רשום את כל foos עם שם מסוים הוא: [hasResponseCollection: {typeName: Foo}]

8. מסקנה

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

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

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

ה יישום מלא של מדריך זה ניתן למצוא בפרויקט github.

הנה ה- API הסופי של RAML במלואו:

#% RAML 1.0 כותרת: Baeldung Foo REST שירותי גרסת API: פרוטוקולי v1: [HTTPS] baseUri: //rest-api.baeldung.com/api/{version} mediaType: יישום / json מאובטח מאת: basicAuth securitySchemes: basicAuth: תיאור: | כל בקשה חייבת להכיל את הכותרות הדרושות לסוג אימות בסיסי: אימות בסיסי המתואר מאת: כותרות: הרשאה: תיאור: | משמש לשליחת פרטי הכניסה המקודדים מסוג "שם משתמש: סיסמה" של Base64: תגובות מחרוזת: 401: תיאור: | לא מורשה. או שילוב שם המשתמש והסיסמה שסופק אינו חוקי, או שהמשתמש אינו רשאי לגשת לתוכן המסופק על ידי כתובת האתר המבוקשת. types: Foo:! include types / Foo.raml Bar:! include types / Bar.raml Error:! include types / Error.raml resourceTypes: collection: use: השתמש במשאב זה Type כדי לייצג אוסף של פריטים תיאור: אוסף של < > קבל: תיאור: | קבל את כל ה <>, מסונן אופציונלי הוא: [hasResponseCollection: {typeName: <>}] פוסט: תיאור: | צור פריט <> is: [hasRequestItem: {typeName: <>}] פריט: use: השתמש במשאב סוג זה כדי לייצג כל תיאור פריט בודד: <> get: description: קבל <> הוא: [hasResponseItem: {typeName : <>}, hasNotFound] put: תיאור: עדכון <> is: [hasRequestItem: {typeName: <>}, hasResponseItem: {typeName: <>}, hasNotFound] מחק: תיאור: מחק a <> הוא: [hasNotFound ] תגובות: 204: תכונות: hasRequestItem: body: application / json: type: <> hasResponseItem: תגובות: 200: body: application / json: type: <> hasResponseCollection: תגובות: 200: body: application / json: type: < > [] hasNotFound: תגובות: 404: body: application / json: type: example error:! include דוגמאות / Error.json / foos: type: {collection: {typeName: Foo}} get: queryParameters: name ?: string string name ?: string / {fooId}: type: {item: {typeName: Foo}} / name / {name}: get: description: רשימת כל foos עם שם מסוים היא: [hasResponseCollection: {typeName: Foo}] / bars : סוג: {collecti ב-: {typeName: Bar}} / {barId}: type: {item: {typeName: Bar}} / fooId / {fooId}: get: description: קבל את כל הסורגים עבור fooId התואם הוא: [hasResponseCollection: {typeName: בר}]

הַבָּא » RAML מודולרי באמצעות כולל, ספריות, שכבות-על והרחבות « מבוא קודם ל- RAML - שפת הדוגמנות RESTful API