תכנות עם ממשקי API של Java, חלק 1: OpenAPI ו- Swagger

בזמן שקיבלתם את הקפה, פיתוח אפליקציות Java השתנה - שוב .

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

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

במדריך דו-חלקי זה תלמד כיצד לשים ממשקי API של Java במרכז התכנון והפיתוח שלך, החל ברעיון ועד קידוד. חלק 1 מתחיל בסקירה כללית ומציג בפניכם את OpenAPI, הידוע גם בשם Swagger. בחלק 2 תלמד כיצד להשתמש בהגדרות ה- API של Swagger לפיתוח אפליקציית MVC של Spring Web עם חזית Angular 2.

מהו API של Java?

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

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

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

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

מתיו טייסון

אז איפה זה משאיר אותנו עם פיתוח מונחה API?

ממשקי API של Java למחשוב ענן, מיקרו-שירותים ו- REST

תכנות עם ממשקי API עולה לידי ביטוי עם ה- API האינטרנטי המודרני: API שנחשף לרשת (NEA) , כאשר הגבול בין מערכות הוא "מעבר לחוט." גבולות אלה כבר מרכזיים באפליקציות אינטרנט, המהוות נקודת המגע הנפוצה בין לקוחות חזיתיים לשרתים עורפיים. מהפכת הענן הגדילה את חשיבותם של ממשקי API של Java באופן אקספוננציאלי.

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

מיקרו-שירותים ו- API ציבורי גדלים משורשי הארכיטקטורה המכוונת לשירות (SOA) ותוכנה כשירות (SaaS). אף על פי ש- SOA הינה מגמה במשך שנים רבות, אימוץ נרחב הוחמר בגלל המורכבות והתקורה של SOA. התעשייה התיישבה עם ממשקי API RESTful כסטנדרט בפועל, ומספקים מספיק מבנה וכינוס עם גמישות רבה יותר בעולם האמיתי. עם REST כרקע, אנו יכולים ליצור הגדרות API רשמיות השומרות על הקריאה האנושית. מפתחים יוצרים כלים סביב הגדרות אלה.

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

שימוש בממשקי API של Java בתכנון

אתה יכול לראות את החשיבות של ממשקי API, אבל איך היית משתמש בהם לטובתך?

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

הבה נבחן כיצד הגדרות Java API מגשרות בין שלבי הרעיון והמימוש בפיתוח.

ממשקי API תיאוריים לעומת מרשמים

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

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

איסוף דרישות עם ממשקי API של Java

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

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

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

  • האפליקציה חייבת להיות מסוגלת ליצור סוג של חלק אופניים (מחליף הילוכים, בלם וכו ').
  • משתמש מורשה חייב להיות מסוגל לרשום, ליצור ולהפוך סוג חלק לפעיל.
  • An unauthorized user must be able to list active part types, and view lists of individual part-type instances in the system.

Already you can see the outlines of services taking shape. With eventual APIs in mind, you can begin sketching out those services. As an example, here's a partial listing of RESTful CRUD services for bike-part types:

  • Create bike part type: PUT /part-type/
  • Update bike part type: POST /part-type/
  • List part types: GET /part-type/
  • Get part type detail: GET /part-type/:id

Notice how the CRUD services begin to hint at the shape of various service boundaries. If you're building in a microservices style, you can already see three microservices emerging from the design:

  • A bike-part service
  • A bike part-type service
  • An authentication/authorization service

Because I think of APIs as boundaries of related entities, I consider the microservices from this list to be API surfaces. Together, they offer a big-picture view of the application architecture. Details of the services themselves are also described in a fashion that you will use for the technical specification, which is the next phase of the software development lifecycle.

Technical specification with Java APIs

If you've included the API focus as part of requirements gathering, then you already have a good framework for technical specification. The next stage is selecting the technology stack you will use to implement the specification.

With so much focus on building RESTful APIs, developers have an embarrassment of riches when it comes to implementation. Regardless of the stack you choose, fleshing out the API even further at this stage will increase your understanding of the app's architectural needs. Options might include a VM (virtual machine) to host the application, a database capable of managing the volume and type of data you're serving, and a cloud platform in the case of IaaS or PaaS deployment.

You can use the API to drive "downward" toward schemas (or document structures n NoSQL), or "upward" toward UI elements. As you develop the API specification, you will likely notice an interplay between these concerns. This is all good and part of the process. The API becomes a central, living place to capture these changes.

Another concern to keep in mind is which public APIs your system will expose. Give extra thought and care to these. Along with assisting in the development effort, public APIs serve as the published contract that external systems use to interface with yours.

Public cloud APIs

In general, APIs define the contract of a software system, providing a known and stable interface against which to program other systems. Specifically, a public cloud API is a public contract with other organizations and programmers building systems. Examples are the GitHub and Facebook APIs.

Documenting the Java API

At this stage, you will want to start capturing your APIs in formal syntax. I've listed a few prominent API standards in Table 1.

Comparing API formats

 
Name Summary Stars on GitHub URL
OpenAPI JSON and YML Supported API Standard descended from the Swagger project, includes variety of tools in the Swagger ecosystem. ~6,500 //github.com/OAI/OpenAPI-Specification
RAML YML based spec supported mainly by MuleSoft ~3,000 //github.com/raml-org/raml-spec
API BluePrint An API design language using MarkDown-like syntax ~5,500 //github.com/apiaryio/api-blueprint/

Virtually any format you choose for documenting your API should be okay. Just look for a format that is structured, has a formal spec and good tooling around it, and looks like it will be actively maintained long term. Both RAML and OpenAPI fit that bill. Another neat project is API Blueprint, which uses markdown syntax. For examples in this article we're going to use OpenAPI and Swagger.

OpenAPI and Swagger

OpenAPI is a JSON format for describing REST-based APIs. Swagger started as OpenAPI, but has evolved into a set of tools around the OpenAPI format. The two technologies complement each other well.

Introducing OpenAPI

OpenAPI is currently the most common choice for creating RESTful definitions. A compelling alternative is RAML (RESTful API Markup Language), which is based on YAML. Personally, I've found the tooling in Swagger (especially the visual designer) more polished and error-free than in RAML.

OpenAPI uses JSON syntax, which is familiar to most developers. If you'd rather not strain your eyes parsing JSON, there are UIs to make working with it easier. Part 2 introduces UIs for RESTful definitions.

Listing 1 is a sample of OpenAPI's JSON syntax.

Listing 1. OpenAPI definition for a simple BikePart

 "paths": { "/part-type": { "get": { "description": "Gets all the part-types available in the system", "operationId": "getPartTypes", "produces": [ "application/json" ], "responses": { "200": { "description": "Gets the BikeParts", "schema": { "type": "array", "items": { "$ref": "#/definitions/BikePart" } } } } } } } 

This definition is so concise it is practically Spartan, which is fine for now. There's plenty of room to increase the detail and complexity of the API definition going forward. I'll show you a more detailed iteration of this definition shortly.

Coding from the Java API

Requirements gathering is done and the basic app has been spec'd out, which means you're ready for the fun part---coding! Having a formal Java API definition gives you some distinct advantages. For one thing, you know what endpoints the back-end and front-end developers need to create and code against, respectively. Even if you are a team of one, you'll quickly see the value of an API-driven approach when you begin coding.

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

מפרט גרעיני יותר וקידוד בפועל עשויים לדרוש פירוט רב יותר מההגדרה הקצרה ברשימה 1. בנוסף, מערכות גדולות ומורכבות יותר עשויות לזכות ביכולות שיגדלו, כמו הפניות למסמכים. רישום 2 מציג דוגמה בולטת יותר ל- API של BikePart.

רישום 2. הוספת פרטים להגדרת ה- BikePart API

 "paths": { "/part-type": { "get": { "description": "Gets all the part-types available in the system", "operationId": "getPartTypes", "produces": [ "application/json" ], "parameters": [ { "name": "limit", "in": "query", "description": "maximum number of results to return", "required": false, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "part-type listing", "schema": { "type": "array", "items": { "$ref": "#/definitions/PartType" } } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/Error" } } } }