Keď ste dostali kávu, vývoj aplikácií Java sa zmenil -ešte raz.
Vo svete poháňanom rýchlymi zmenami a inováciami je ironické, že sa API vracajú na scénu. Rovnako ako kódovací ekvivalent systému metra v New Yorku v dobe autonómnych automobilov, sú aj API stará technológia--staroveké, ale nevyhnutné. Zaujímavé je, ako sa táto neviditeľná každodenná architektúra IT znovu predstavuje a používa v súčasných technologických trendoch.
Aj keď sú rozhrania API všade, stali sa obzvlášť prominentnými vo svojej vzdialenej inkarnácii ako služby RESTful, ktoré sú chrbticou cloudových nasadení. Cloudové služby sú verejné API, ktoré sa vyznačujú koncovými bodmi zameranými na verejnosť a zverejnenými štruktúrami. Cloudové aplikácie majú tiež trend smerom k mikroslužby, ktoré sú nezávislé, ale súvisia s nasadením. Všetky tieto faktory zvyšujú dôležitosť API.
V tomto dvojdielnom výučbe sa dozviete, ako umiestniť Java API do jadra vášho procesu návrhu a vývoja, od konceptu po kódovanie. 1. časť začína prehľadom a predstavuje vám OpenAPI, tiež známy ako Swagger. V časti 2 sa naučíte, ako používať definície rozhrania API spoločnosti Swagger na vývoj aplikácie Spring Web MVC s rozhraním Angular 2.
Čo je to Java API?
API sú pri vývoji softvéru také bežné, že sa niekedy predpokladá, že programátori jednoducho vedia, o čo ide. Skôr ako sa spoliehajme na osmózu, venujme chvíľu rozbaleniu toho, čo máme na mysli, keď hovoríme o API.
Všeobecne sa dá povedať, že API nastavujú a spravujú hranice medzi systémami.Najprv, API znamená „aplikačné programovacie rozhranie“. Úlohou API je určiť, ako softvérové komponenty interagujú. Ak ste oboznámení s objektovo orientovaným programovaním, poznáte rozhrania API v ich inkarnácii ako rozhrania a triedy používané na získanie prístupu k základným funkciám jazyka alebo ako verejnú tvár knižníc tretích strán a funkcií operačného systému.
Všeobecne môžeme povedať, že API nastavujú a spravujú hranice medzi systémami, ako je to znázornené na obrázku 1.
Matthew Tyson Kde nás to teda nechá s vývojom založeným na API?
Rozhrania Java API pre cloudové výpočty, mikroslužby a REST
Programovanie pomocou API prichádza do popredia s moderným webovým API: a sieťovo exponované API (NEA), kde hranica medzi systémami je „cez kábel“. Tieto hranice sú už ústredné pre webové aplikácie, ktoré sú spoločným kontaktným bodom medzi klientmi front-end a servermi typu back-end. Cloudová revolúcia exponenciálne zvýšila dôležitosť Java API.
Akákoľvek programátorská aktivita, ktorá si vyžaduje náročné cloudové služby (čo sú v podstate verejné API) a dekonštrukcia systémov na menšie, nezávislé, ale súvisiace nasadenia (známe tiež ako mikroslužby), sa vo veľkej miere spolieha na API. Sieťovo exponované API sú jednoducho univerzálnejšie, ľahšie sa získavajú a ľahšie sa upravujú a rozširujú ako tradičné API. Aktuálnym architektonickým trendom je zužitkovať tieto vlastnosti.
Mikroslužby a verejné API vyrastajú z koreňov architektúry orientovanej na služby (SOA) a softvéru ako služby (SaaS). Aj keď je SOA trendom už mnoho rokov, komplexnosť a réžia SOA brzdila rozsiahle prijatie. Odvetvie sa rozhodlo pre RESTful API ako de facto štandard, ktorý poskytuje dostatočnú štruktúru a konvencie s väčšou flexibilitou v reálnom svete. S prostredím REST môžeme vytvárať formálne definície API, ktoré si zachovajú ľudskú čitateľnosť. Vývojári vytvárajú okolo týchto definícií nástroje.
Vo všeobecnosti je REST konvencia na mapovanie zdrojov na cesty HTTP a ich príslušné akcie. Pravdepodobne ste ich videli ako metódy HTTP GET a POST. Kľúčové je použiť samotný HTTP ako štandard a navrstviť na to konvenčné mapovania kvôli predvídateľnosti.
Používanie Java API v dizajne
Vidíte dôležitosť API, ale ako by ste ich využili vo svoj prospech?
Používanie definícií Java API na podporu procesu navrhovania a vývoja je efektívnym spôsobom, ako štruktúrovať svoje myslenie o systémoch IT. Použitím definícií Java API od samého začiatku životného cyklu vývoja softvéru (zhromažďovanie koncepcií a požiadaviek) vytvoríte hodnotný technický artefakt, ktorý je užitočný už pri nasadení, ako aj pri priebežnej údržbe.
Uvažujme, ako definície Java API premosťujú koncepčné a implementačné fázy vývoja.
Popisné a predpísané API
Je užitočné rozlišovať medzi popisnými a normatívnymi API. A popisné API popisuje spôsob, akým kód v skutočnosti funguje, zatiaľ čo a normatívne API popisuje, ako sa kód by mal funkcia.
Oba tieto štýly sú užitočné a oba sú výrazne vylepšené použitím štruktúrovaného štandardného formátu pre definíciu API. Pravidlom je, že použitie API na vytváranie kódu je predpísaným použitím, zatiaľ čo použitie kódu na výstup definície rozhrania Java API je popisné.
Zhromažďovanie požiadaviek pomocou Java API
Pokiaľ ide o spektrum koncepcie od implementácie, zhromažďovanie požiadaviek je na konci koncepcie. Ale už v koncepčnej fáze vývoja aplikácií môžeme začať uvažovať o API.
Povedzme, že váš systémový dizajn sa zaoberá horskými bicyklami - konštrukciou, dielmi atď. Ako objektovo orientovaný vývojár by ste začali rozhovorom so zainteresovanými stranami o požiadavkách. Pomerne rýchlo po tom by ste premýšľali nad abstraktom BikePart trieda.
Ďalej by ste premýšľali prostredníctvom webovej aplikácie, ktorá by spravovala rôzne objekty častí bicyklov. Čoskoro by ste dospeli k bežným požiadavkám na správu týchto častí bicykla. Tu je prehľad fáza požiadaviek dokumentácie pre aplikáciu súčiastky na bicykel:
- Aplikácia musí byť schopná vytvoriť typ časti bicykla (radiaca páka, brzda atď.).
- Autorizovaný užívateľ musí byť schopný vypísať, vytvoriť a aktivovať typ súčasti.
- Neautorizovaný užívateľ musí byť schopný zoznam aktívnych typov dielov a zoznamy jednotlivých inštancií typov dielov v systéme.
Už vidíte, ako sa formujú obrysy služieb. S ohľadom na prípadné API môžete tieto služby začať skicovať. Ako príklad uvádzame čiastočný zoznam služieb RESTful CRUD pre typy častí bicyklov:
- Vytvorte typ časti bicykla:
PUT / čiastočný typ / - Aktualizácia typu časti bicykla:
POST / diel-typ / - Zoznam typov dielov:
ZÍSKAŤ / časť-typ / - Získať podrobnosť o type dielu:
GET / part-type /: id
Všimnite si, ako služby CRUD začínajú naznačovať tvar rôznych hraníc služieb. Ak staviate v štýle mikroslužieb, môžete už z návrhu vidieť tri mikroslužby:
- Servis bicyklov
- Servis typu bicyklov
- Služba autentifikácie / autorizácie
Pretože o API myslím ako hranice príbuzných subjektov, Mikroslužby z tohto zoznamu považujem za API povrchy. Spoločne ponúkajú celkový pohľad na architektúru aplikácií. Podrobnosti o samotných službách sú tiež opísané spôsobom, ktorý použijete pri technickej špecifikácii, ktorá predstavuje ďalšiu fázu životného cyklu vývoja softvéru.
Technická špecifikácia s Java API
Ak ste zahrnuli zameranie API ako súčasť zhromažďovania požiadaviek, potom už máte dobrý rámec pre technické špecifikácie. Ďalšou etapou je výber technologického radu, ktorý použijete na implementáciu špecifikácie.
S toľkým zameraním na budovanie rozhraní RESTful API majú vývojári pri implementácii rozpaky z bohatstva. Bez ohľadu na to, aký zásobník si vyberiete, dokončenie API ešte v tejto fáze zvýši vaše pochopenie architektonických potrieb aplikácie. Medzi možnosti patrí VM (virtuálny počítač) na hosťovanie aplikácie, databáza schopná spravovať objem a typ údajov, ktoré poskytujete, a cloudová platforma v prípade nasadenia IaaS alebo PaaS.
Pomocou rozhrania API môžete smerovať „smerom nadol“ smerom k schémam (alebo štruktúram dokumentov v NoSQL) alebo „smerom hore“ k prvkom používateľského rozhrania. Pri vývoji špecifikácie API si pravdepodobne všimnete súhru týchto obáv. To je všetko dobré a súčasť procesu. API sa stáva ústredným živým miestom na zachytávanie týchto zmien.
Nezabudnite tiež na to, ktoré verejné rozhrania API váš systém vystaví. Venujte týmto osobitnú pozornosť a starostlivosť. Verejné API slúžia spolu s pomocou pri vývoji a vývoji ako zverejnená zmluva, ktorú používajú externé systémy na prepojenie s vašimi.
Verejné cloudové API
Všeobecne API definujú zmluvu softvérového systému a poskytujú známe a stabilné rozhranie, na základe ktorého je možné programovať ďalšie systémy. Verejné cloudové API je konkrétne verejná zmluva s inými organizáciami a programátormi, ktorí vytvárajú systémy. Príkladom sú API GitHub a Facebook.
Dokumentácia rozhrania Java API
V tejto fáze budete chcieť začať zachytávať svoje API vo formálnej syntaxi. V tabuľke 1 som uviedol niekoľko významných štandardov API.
Porovnávanie formátov API
| názov | Zhrnutie | Hviezdy na GitHub | URL |
|---|---|---|---|
| OpenAPI | Štandard API podporovaný JSON a YML pochádzajúci z projektu Swagger obsahuje rôzne nástroje v ekosystéme Swagger. | ~6,500 | //github.com/OAI/OpenAPI-špecifikácia |
| RAML | Špecifikácie založené na YML podporované hlavne MuleSoftom | ~3,000 | //github.com/raml-org/raml-spec |
| API BluePrint | Dizajnový jazyk API využívajúci syntax podobnú MarkDown | ~5,500 | //github.com/apiaryio/api-blueprint/ |
Prakticky akýkoľvek formát, ktorý si zvolíte na zdokumentovanie vášho API, by mal byť v poriadku. Stačí sa pozrieť na formát, ktorý je štruktúrovaný, má formálne špecifikácie a dobré nástroje a vyzerá to, že bude dlhodobo aktívne udržiavaný. RAML aj OpenAPI zapadajú do tohto zákona. Ďalším elegantným projektom je API Blueprint, ktorý používa syntax markdown. Pre príklady v tomto článku budeme používať OpenAPI a Swagger.
OpenAPI a Swagger
OpenAPI je formát JSON na popis rozhraní API založených na REST. Swagger začínal ako OpenAPI, ale vyvinul sa do súboru nástrojov okolo formátu OpenAPI. Tieto dve technológie sa navzájom dobre dopĺňajú.
Predstavujeme OpenAPI
OpenAPI je v súčasnosti najbežnejšou voľbou na vytváranie definícií RESTful. Pútavou alternatívou je RAML (RESTful API Markup Language), ktorý je založený na YAML. Osobne som našiel nástroje vo Swagger (hlavne vizuálny dizajnér) vyleštenejšie a bezchybnejšie ako v RAML.
OpenAPI používa syntax JSON, ktorú pozná väčšina vývojárov. Ak radšej nechcete namáhať oči pri analýze súborov JSON, existujú používateľské rozhrania, ktoré vám uľahčia prácu s ním. Časť 2 predstavuje používateľské rozhrania pre definície RESTful.
Zoznam 1 je ukážkou syntaxe JSON OpenAPI.
Zoznam 1. Definícia OpenAPI pre jednoduchý BikePart
"paths": {"/ part-type": {"get": {"description": "Získava všetky typy častí dostupné v systéme", "operationId": "getPartTypes", "produce": ["aplikácia / json "]," responses ": {" 200 ": {" description ":" Získava BikeParts "," schema ": {" type ":" pole "," items ": {" $ ref ":" # / definitions / BikePart "}}}}}}} Táto definícia je taká stručná, že je v skutočnosti sparťanská, čo je zatiaľ v poriadku. Je tu veľa priestoru na zvýšenie podrobností a zložitosti definície API do budúcnosti. V krátkosti vám ukážem podrobnejšiu iteráciu tejto definície.
Kódovanie z Java API
Zhromažďovanie požiadaviek je hotové a základná aplikácia bola špecifikovaná, čo znamená, že ste pripravení na zábavnú časť - kódovanie! Formálna definícia rozhrania Java API vám dáva niekoľko zreteľných výhod. Jednak viete, aké koncové body musia vývojári typu back-end a front-end vytvárať a proti ktorým kódovať. Aj keď ste tím jedného, po začiatku programovania rýchlo uvidíte hodnotu prístupu založeného na API.
Pri vytváraní aplikácie uvidíte tiež hodnotu použitia rozhraní API na zachytenie spätného rokovania medzi vývojom a podnikaním. Používanie nástrojov API urýchli aplikáciu aj dokumentovanie zmien kódu.
Podrobnejšie špecifikácie a skutočné kódovanie môžu vyžadovať viac podrobností ako stručná definícia v zozname 1. Okrem toho by si väčšie a zložitejšie systémy mohli zaslúžiť možnosti, ktoré sa budú zväčšovať, napríklad odkazy na dokumenty. Výpis 2 zobrazuje podrobnejší príklad rozhrania BikePart API.
Zoznam 2. Pridanie podrobností k definícii rozhrania BikePart API
"paths": {"/ part-type": {"get": {"description": "Získava všetky typy častí dostupné v systéme", "operationId": "getPartTypes", "produkuje": ["aplikácia / json "]," parameters ": [{" name ":" limit "," in ":" query "," description ":" maximálny počet výsledkov, ktoré sa majú vrátiť "," povinný ": false," type ": "integer", "format": "int32"}], "response": {"200": {"description": "výpis typu časti", "schéma": {"type": "pole", "položky" ": {" $ ref ":" # / definitions / PartType "}}}," default ": {" description ":" neočakávaná chyba "," schéma ": {" $ ref ":" # / definície / chyba " }}}} 
