Zatímco jste dostávali kávu, vývoj Java aplikací se změnil -znovu.
Ve světě poháněném rychlými změnami a inovacemi je ironií, že API se vrací. Stejně jako kódovací ekvivalent systému metra v New Yorku ve věku autonomních automobilů, API jsou stará technologie--starověké, ale nepostradatelné. Zajímavé je, jak je tato neviditelná každodenní IT architektura znovu představena a použita v současných technologických trendech.
Zatímco API jsou všude, ve své vzdálené inkarnaci se staly obzvláště prominentními jako služby RESTful, které jsou páteří cloudových nasazení. Cloudové služby jsou veřejné API, které se vyznačují veřejnými cíli a zveřejněnými strukturami. Cloudové aplikace také směřují k trendu mikroslužby, což jsou nezávislá, ale související nasazení. Všechny tyto faktory zvyšují důležitost API.
V tomto dvoudílném výukovém programu se naučíte, jak dát Java API do jádra vašeho procesu návrhu a vývoje, od konceptu po kódování. Část 1 začíná přehledem a seznamuje vás s OpenAPI, také známým jako Swagger. V části 2 se naučíte, jak používat definice API Swagger k vývoji aplikace Spring Web MVC s rozhraním Angular 2.
Co je to Java API?
API jsou ve vývoji softwaru tak běžná, že se někdy předpokládá, že programátoři jednoduše vědí, o co jde. Spíše než spoléhat na osmózu, pojďme chvíli rozbalit, co máme na mysli, když mluvíme o API.
Obecně lze říci, že rozhraní API nastavují a spravují hranice mezi systémy.První, API znamená „aplikační programovací rozhraní“. Úlohou API je určit, jak softwarové komponenty interagují. Pokud jste obeznámeni s objektově orientovaným programováním, znáte API v jejich inkarnaci jako rozhraní a třídy používané k získání přístupu k základním funkcím jazyka nebo jako veřejná tvář knihoven třetích stran a schopností OS.
Obecně lze říci, že rozhraní API nastavují a spravují hranice mezi systémy, jak je vidět na obrázku 1.
Matthew Tyson Kde nás to tedy nechá s vývojem založeným na API?
Java API pro cloud computing, mikroslužby a REST
Programování pomocí API přichází do popředí s moderním webovým API: a síťově exponované API (NEA), kde hranice mezi systémy je „přes drát“. Tyto hranice jsou již ústředním bodem webových aplikací, které jsou běžným kontaktním bodem mezi klienty front-end a servery typu back-end. Cloudová revoluce exponenciálně zvýšila důležitost Java API.
Jakákoli programovací aktivita, která vyžaduje náročné cloudové služby (což jsou v zásadě veřejné API) a dekonstruování systémů na menší, nezávislá, ale související nasazení (známá také jako mikroslužby), se silně spoléhá na API. Síťově exponovaná API jsou jednoduše univerzálnější, snáze získatelná a snadněji upravitelná a rozšířená než tradiční API. Současným architektonickým trendem je využití těchto funkcí.
Mikroslužby a veřejné API jsou pěstovány od kořenů architektury orientované na služby (SOA) a softwaru jako služby (SaaS). Přestože SOA je trendem po mnoho let, její široké přijetí bylo omezeno složitostí a režijními náklady SOA. Průmysl se usadil na RESTful API jako de facto standardu, který poskytuje jen dost struktury a konvence s větší flexibilitou v reálném světě. S prostředím REST můžeme vytvářet formální definice API, které si zachovají lidskou čitelnost. Vývojáři vytvářejí nástroje kolem těchto definic.
Obecně je REST konvence pro mapování prostředků na cesty HTTP a jejich přidružené akce. Pravděpodobně jste je viděli jako metody HTTP GET a POST. Klíčem je použití samotného protokolu HTTP jako standardu a navýšení vrstev konvenčních mapování pro předvídatelnost.
Použití Java API v designu
Vidíte důležitost API, ale jak byste je využili ve svůj prospěch?
Použití definic Java API k řízení procesu návrhu a vývoje je efektivní způsob, jak strukturovat vaše myšlení o systémech IT. Použitím definic Java API od samého začátku životního cyklu vývoje softwaru (shromažďování konceptů a požadavků) vytvoříte cenný technický artefakt, který je užitečný hned po nasazení i pro průběžnou údržbu.
Zvažme, jak definice rozhraní Java API překlenují koncepční a implementační fáze vývoje.
Popisné vs. předepisující API
Je užitečné rozlišovat mezi popisnými a normativními API. A popisné API popisuje způsob, jakým kód ve skutečnosti funguje, zatímco a preskriptivní API popisuje, jak kód by měl funkce.
Oba tyto styly jsou užitečné a oba jsou výrazně vylepšeny pomocí strukturovaného standardního formátu pro definici API. Pravidlem je, že použití API k vytváření kódu je normativní použití, zatímco použití kódu k výstupu definice Java API je popisné použití.
Shromažďování požadavků pomocí rozhraní Java API
Ve spektru konceptu k implementaci je shromažďování požadavků na koncepční straně. Ale i v koncepční fázi vývoje aplikací můžeme začít uvažovat o API.
Řekněme, že váš systém v designu se zabývá horskými koly - konstrukcí, součástmi atd. Jako objektově orientovaný vývojář byste začali mluvit o požadavcích se zúčastněnými stranami. Poměrně rychle po tom byste přemýšleli o abstraktu BikePart třída.
Dále byste přemýšleli prostřednictvím webové aplikace, která by spravovala různé objekty částí kola. Brzy byste dospěli k běžným požadavkům na správu těchto dílů na kole. Tady je snímek fáze požadavků dokumentace pro aplikaci dílů na kolo:
- Aplikace musí být schopna vytvořit typ součásti kola (řadicí páka, brzda atd.).
- Oprávněný uživatel musí být schopen vytvořit seznam, vytvořit a aktivovat typ součásti.
- Neoprávněný uživatel musí být schopen zobrazit seznam aktivních typů součástí a zobrazit seznamy jednotlivých instancí typů součástí v systému.
Už vidíte obrysy služeb, které se formují. S ohledem na případná rozhraní API můžete začít tyto služby skicovat. Jako příklad uvádíme částečný seznam služeb RESTful CRUD pro typy dílů pro kola:
- Vytvořit typ součásti kola:
PUT / dílčí typ / - Aktualizovat typ součásti kola:
POST / typ dílu / - Seznam typů dílů:
ZÍSKAT / část-typ / - Získejte podrobnosti o typu dílu:
GET / part-type /: id
Všimněte si, jak služby CRUD začínají naznačovat tvar různých hranic služeb. Pokud stavíte ve stylu mikroslužeb, můžete již vidět tři mikroslužby vycházející z návrhu:
- Servis na kola
- Služba typu kola
- Služba ověřování / autorizace
Protože myslím na API jako hranice souvisejících entit, Považuji mikroslužby z tohoto seznamu za API povrchy. Společně nabízejí celkový pohled na architekturu aplikace. Podrobnosti o samotných službách jsou také popsány způsobem, který použijete pro technickou specifikaci, což je další fáze životního cyklu vývoje softwaru.
Technická specifikace s Java API
Pokud jste začlenili zaměření API jako součást shromažďování požadavků, pak již máte dobrý rámec pro technické specifikace. Další fází je výběr technologického zásobníku, který použijete k implementaci specifikace.
S tak velkým zaměřením na budování RESTful API mají vývojáři při implementaci rozpaky bohatství. Bez ohledu na zásobník, který si vyberete, rozšíření API ještě v této fázi zvýší vaše porozumění architektonickým potřebám aplikace. Možnosti mohou zahrnovat virtuální počítač (virtuální počítač) pro hostování aplikace, databázi schopnou spravovat objem a typ dat, která poskytujete, a cloudovou platformu v případě nasazení IaaS nebo PaaS.
Rozhraní API můžete použít k jízdě „směrem dolů“ směrem ke schématům (nebo strukturám dokumentů v NoSQL) nebo „směrem nahoru“ k prvkům uživatelského rozhraní. Při vývoji specifikace API si pravděpodobně všimnete souhry mezi těmito obavami. To je vše dobré a součást procesu. API se stává ústředním živým místem pro zachycení těchto změn.
Dalším problémem, který je třeba mít na paměti, je, které veřejné API váš systém vystaví. Věnujte jim zvláštní pozornost a péči. Spolu s asistencí při vývoji slouží veřejné API jako publikovaná smlouva, kterou externí systémy používají k propojení s vašimi.
Veřejná cloudová rozhraní API
Obecně platí, že API definují kontrakt softwarového systému a poskytují známé a stabilní rozhraní, na jehož základě lze programovat další systémy. Konkrétně je API veřejného cloudu veřejnou smlouvou s jinými organizacemi a programátory, kteří vytvářejí systémy. Příkladem jsou API GitHub a Facebook.
Dokumentace Java API
V této fázi budete chtít začít zachycovat vaše API ve formální syntaxi. V tabulce 1 jsem uvedl několik významných standardů API.
Porovnání formátů API
| název | souhrn | Hvězdy na GitHubu | URL |
|---|---|---|---|
| OpenAPI | Standard API podporovaný JSON a YML pocházející z projektu Swagger zahrnuje řadu nástrojů v ekosystému Swagger. | ~6,500 | //github.com/OAI/OpenAPI-Specification |
| RAML | Specifikace založená na YML podporovaná hlavně MuleSoft | ~3,000 | //github.com/raml-org/raml-spec |
| API BluePrint | Návrhový jazyk API pomocí syntaxe podobné MarkDown | ~5,500 | //github.com/apiaryio/api-blueprint/ |
Prakticky jakýkoli formát, který zvolíte pro dokumentaci svého API, by měl být v pořádku. Stačí se podívat na formát, který je strukturovaný, má formální specifikaci a dobré nástroje a vypadá, že bude dlouhodobě aktivně udržován. RAML i OpenAPI odpovídají tomuto účtu. Dalším čistým projektem je API Blueprint, který používá syntaxi markdown. Pro příklady v tomto článku použijeme OpenAPI a Swagger.
OpenAPI a Swagger
OpenAPI je formát JSON pro popis API založených na REST. Swagger začínal jako OpenAPI, ale vyvinul se do sady nástrojů kolem formátu OpenAPI. Obě technologie se dobře doplňují.
Představujeme OpenAPI
OpenAPI je v současnosti nejběžnější volbou pro vytváření definic RESTful. Zajímavou alternativou je RAML (RESTful API Markup Language), který je založen na YAML. Osobně jsem našel nástroje ve Swagger (zejména vizuální návrhář) vyleštěnější a bezchybnější než v RAML.
OpenAPI používá syntaxi JSON, kterou zná většina vývojářů. Pokud byste raději nenamáhali oči při analýze JSON, existují uživatelská rozhraní, která vám usnadní práci s ním. Část 2 zavádí uživatelská rozhraní pro RESTful definice.
Výpis 1 je ukázkou syntaxe JSON OpenAPI.
Výpis 1. Definice OpenAPI pro jednoduchý BikePart
"paths": {"/ part-type": {"get": {"description": "Získá všechny typy součástí dostupné v systému", "operationId": "getPartTypes", "vytváří": ["aplikace / json "]," responses ": {" 200 ": {" description ":" Získá BikeParts "," schema ": {" type ":" pole "," items ": {" $ ref ":" # / definice / BikePart "}}}}}}} Tato definice je tak stručná, že je prakticky sparťanská, což je zatím v pořádku. Existuje spousta prostoru pro zvýšení podrobností a složitosti definice API do budoucna. Brzy vám ukážu podrobnější iteraci této definice.
Kódování z Java API
Shromažďování požadavků je hotové a základní aplikace byla specifikována, což znamená, že jste připraveni na zábavnou část - kódování! Formální definice Java API vám dává některé výrazné výhody. Za prvé víte, jaké koncové body musí vývojáři back-endu a front-endu vytvářet a kódovat. I když jste tým jednoho, rychle uvidíte hodnotu přístupu založeného na API, když začnete kódovat.
Při vytváření aplikace uvidíte také hodnotu použití rozhraní API k zachycení vzájemného vyjednávání mezi vývojem a podnikáním. Použití nástrojů API urychlí použití i dokumentování změn kódu.
Podrobnější specifikace a skutečné kódování mohou vyžadovat více podrobností než stručná definice v seznamu 1. Kromě toho by si větší a složitější systémy mohly zasloužit schopnosti, které se budou měnit, například odkazy na dokumenty. Výpis 2 ukazuje podrobnější příklad rozhraní BikePart API.
Výpis 2. Přidání podrobností do definice rozhraní BikePart API
"paths": {"/ part-type": {"get": {"description": "Získá všechny typy součástí dostupné v systému", "operationId": "getPartTypes", "vytváří": ["aplikace / json "]," parameters ": [{" name ":" limit "," in ":" query "," description ":" maximální počet výsledků, které se mají vrátit "," required ": false," type ": "integer", "format": "int32"}], "response": {"200": {"description": "výpis typu součásti", "schéma": {"type": "pole", "položky ": {" $ ref ":" # / definitions / PartType "}}}," default ": {" description ":" neočekávaná chyba "," schéma ": {" $ ref ":" # / definice / chyba " }}}} 
