REST API גילוי ו- HATEOAS

REST למעלה

רק הכרזתי על החדש למד אביב קורס, המתמקד ביסודות האביב 5 ומגף האביב 2:

>> בדוק את הקורס

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

מאמר זה יתמקד ב גילוי של REST API, HATEOAS ותרחישים מעשיים המונעים על ידי מבחנים.

2. מדוע להפוך את ה- API לגלוי

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

כדי להבין את הגילוי, עלינו להבין את האילוץ של Hypermedia כ- Engine of Application State (HATEOAS). אילוץ זה של ממשק API של REST נוגע לגילוי מלא של פעולות / מעברים במשאב מ- Hypermedia (Hypertext באמת), כמנהיג היחיד של מצב היישום.

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

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

3. תרחישים של גילוי (מונע על ידי בדיקות)

אז מה המשמעות של שירות REST שניתן לגלות?

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

3.1. גלה את שיטות ה- HTTP התקפות

כאשר שירות REST נצרך בשיטת HTTP לא חוקית, התגובה צריכה להיות שיטת 405 שלא מותרת.

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

@Test הציבור בטל כאשרInvalidPOSTIsSentToValidURIOfResource_thenAllowHeaderListsTheAllowedAtions () {// ניתן מחרוזת uriOfExistingResource = restTemplate.createResource (); // כאשר תגובה res = givenAuth (). פוסט (uriOfExistingResource); // ואז String allowHeader = res.getHeader (HttpHeaders.ALLOW); assertThat (allowHeader, AnyOf.anyOf (containString ("GET"), containString ("PUT"), containString ("DELETE"))); }

3.2. גלה את ה- URI של משאבים שנוצרו לאחרונה

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

כעת, אם הלקוח מבצע GET ב- URI זה, המשאב צריך להיות זמין:

@Test הציבור בטל כאשר ResourceIsCreated_thenUriOfTheNewlyCreatedResourceIsDiscoverable () {// When Foo newResource = new Foo (randomAlphabetic (6)); תגובה createResp = givenAuth (). ContentType ("application / json") .body (unresistedResource) .post (getFooURL ()); מחרוזת uriOfNewResource = createResp.getHeader (HttpHeaders.LOCATION); // ואז תגובה תגובה = givenAuth (). כותרת ראש (HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_VALUE) .get (uriOfNewResource); Foo resourceFromServer = response.body (). כמו (Foo.class); assertThat (newResource, equalTo (resourceFromServer)); }

המבחן מתרחש לפי תרחיש פשוט: יצירת חדש פו ואז להשתמש בתגובת HTTP כדי לגלות את ה- URI היכן שהמשאב זמין כעת. לאחר מכן הוא מבצע GET ב- URI כדי לאחזר את המשאב ומשווה אותו למקור. זאת על מנת לוודא שהוא נשמר כהלכה.

3.3. גלה את ה- URI כדי להשיג את כל המשאבים מסוג זה

כשאנחנו מקבלים משהו מסוים פו אנו צריכים להיות מסוגלים לגלות מה נוכל לעשות בהמשך: אנו יכולים לרשום את כל הזמינים פו אֶמְצָעִי. לפיכך, פעולת אחזור המשאב צריכה לכלול בתגובתה תמיד את ה- URI היכן להשיג את כל המשאבים מאותו סוג.

לשם כך, אנו יכולים שוב להשתמש ב- קישור כּוֹתֶרֶת:

@ מבחן ציבורי בטל כאשר ResourceIsRetrieved_thenUriToGetAllResourcesIsDiscoverable () {// ניתן מחרוזת uriOfExistingResource = createAsUri (); // כאשר תגובה getResponse = givenAuth (). קבל (uriOfExistingResource); // ואז מחרוזת uriToAllResources = HTTPLinkHeaderUtil .extractURIByRel (getResponse.getHeader ("קישור"), "אוסף"); תגובה getAllResponse = givenAuth (). Get (uriToAllResources); assertThat (getAllResponse.getStatusCode (), הוא (200)); }

שים לב שהקוד המלא ברמה נמוכה עבור extractURIByRel - אחראי על חילוץ ה- URI על ידי rel הקשר מוצג כאן.

מבחן זה מכסה את הנושא הקוצני של קשרי קישורים ב- REST: ה- URI לאחזר את כל המשאבים המשתמשים ב- rel = "אוסף" סֵמַנטִיקָה.

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

4. אפשרויות URI ומיקרו פורמטים פוטנציאליים אחרים

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

לדוגמה, הלקוח אמור להיות מסוגל לגלות את ה- URI ליצירת משאבים חדשים בעת ביצוע לקבל על משאב ספציפי. למרבה הצער, אין קשר קישור למודל לִיצוֹר סֵמַנטִיקָה.

למרבה המזל, זה נוהג סטנדרטי ש- URI ליצירה זהה ל- URI כדי להשיג את כל המשאבים מהסוג הזה, כאשר ההבדל היחיד הוא שיטת POST HTTP.

5. מסקנה

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

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

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

REST תחתון

רק הכרזתי על החדש למד אביב קורס, המתמקד ביסודות האביב 5 ומגף האביב 2:

>> בדוק את הקורס

$config[zx-auto] not found$config[zx-overlay] not found