Programavimas

Programavimas naudojant „Java“ API, 1 dalis: „OpenAPI“ ir „Swagger“

Kol ruošiatės kavą, pasikeitė „Java“ programų kūrimas -vėl.

Sparčių pokyčių ir naujovių skatinamame pasaulyje yra ironiška, kad API grįžta. Kaip ir Niujorko metro sistemos kodavimo atitikmuo autonominių automobilių amžiuje, taip ir API senoji technika- senas, bet nepakeičiamas. Įdomu tai, kaip ši nematoma kasdieninė IT architektūra yra permąstoma ir naudojama dabartinėse technologijų tendencijose.

Nors API yra visur, jos tapo ypač ryškios savo nuotoliniame įsikūnijime kaip „RESTful“ paslaugos, kurios yra debesų diegimo pagrindas. Debesų paslaugos yra viešosios API, kuriems būdingi visuomenei skirti galiniai taškai ir paskelbtos struktūros. Debesų programos taip pat linksta mikropaslaugos, kurios yra nepriklausomos, bet susijusios dislokacijos. Visi šie veiksniai padidina API svarbą.

Šioje dviejų dalių pamokoje sužinosite, kaip „Java“ API skirti projektavimo ir kūrimo proceso centre - nuo koncepcijos iki kodavimo. 1 dalis prasideda apžvalga ir supažindina su „OpenAPI“, dar vadinama „Swagger“. 2 dalyje sužinosite, kaip naudoti „Swagger“ API apibrėžimus kuriant „Spring Web MVC“ programą su „Angular 2“ priekine sąsaja.

Kas yra „Java“ API?

API yra tokia įprasta programinės įrangos kūrimo srityje, kad kartais daroma prielaida, kad programuotojai tiesiog žino, kas jie yra. Užuot pasikliavę osmosu, skirkime minutę, kad išpakuotume tai, ką turime omenyje kalbėdami apie API.

Apskritai galime sakyti, kad API nustato ir valdo ribas tarp sistemų.

Pirmas, API reiškia „programų programavimo sąsaja“. API vaidmuo yra nurodyti, kaip sąveikauja programinės įrangos komponentai. Jei esate susipažinęs su objektyviu programavimu, žinote, kad API yra jų įsikūnijimas, kaip sąsajos ir klasės, naudojamos prieigai prie pagrindinių kalbos funkcijų, arba kaip viešas trečiųjų šalių bibliotekų ir OS galimybių veidas.

Apskritai galime sakyti, kad API nustato ir valdo ribas tarp sistemų, kaip parodyta 1 paveiksle.

Matthew Tysonas

Taigi, kur tai palieka mums API pagrįstą plėtrą?

„Java“ API, skirtos debesų kompiuterijai, mikropaslaugoms ir REST

Programavimas naudojant API išryškėja naudojant šiuolaikinę žiniatinklio API: a tinklo veikiama API (NEA), kur riba tarp sistemų yra „per laidą“. Šios ribos jau yra svarbiausios žiniatinklio programose, kurios yra bendras sąsajos taškas tarp „front-end“ klientų ir „back-end“ serverių. Debesų revoliucija eksponentiškai padidino „Java“ API svarbą.

Bet kokia programavimo veikla, kuriai reikalingas debesijos paslaugų (kurios iš esmės yra viešos API), vartojimas ir sistemų dekonstravimas į mažesnes, nepriklausomas, bet susijusias diegimo sistemas (taip pat žinomas kaip mikroservisai), labai priklauso nuo API. Tinklo veikiamos API yra tiesiog universalesnės, lengviau gaunamos ir lengviau modifikuojamos bei išplėstos nei tradicinės API. Dabartinė architektūros tendencija yra išnaudoti šias savybes.

Mikroservisai ir viešosios API yra sukurtos iš į paslaugas orientuotos architektūros (SOA) ir programinės įrangos kaip paslaugos (SaaS) šaknų. Nors SOA buvo tendencija daugelį metų, visuotiniam įsisavinimui trukdė SOA sudėtingumas ir pridėtinės išlaidos. Pramonė apsisprendė su „RESTful“ API kaip de facto standartu, suteikiančiu tik pakankamai struktūrą ir susitarimus, suteikiančius daugiau lankstumo realiame pasaulyje. Kai „REST“ yra fonas, galime sukurti oficialius API apibrėžimus, kurie išlaiko žmonių įskaitomumą. Kūrėjai sukuria įrankius pagal šiuos apibrėžimus.

Apskritai, REST yra išteklių susiejimo su HTTP keliais ir su jais susijusių veiksmų sutartis. Jūs tikriausiai matėte tai kaip HTTP GET ir POST metodus. Svarbiausia yra naudoti patį HTTP kaip standartą, o norint nuspėti, ant jo sluoksniuoti įprastus susiejimus.

Java API naudojimas projektuojant

Galite pamatyti API svarbą, bet kaip jas panaudotumėte savo naudai?

„Java“ API apibrėžimų naudojimas kuriant projektavimo ir kūrimo procesą yra efektyvus būdas susisteminti mąstymą apie IT sistemas. Naudodami „Java“ API apibrėžimus nuo pat programinės įrangos kūrimo gyvavimo ciklo pradžios (koncepcijos ir reikalavimų rinkimo), sukursite vertingą techninį artefaktą, kuris bus naudingas iki diegimo, taip pat atliekant nuolatinę priežiūrą.

Panagrinėkime, kaip „Java“ API apibrėžimai sujungia konceptualius ir įgyvendinimo etapus.

Aprašomosios ir nurodomosios API

Naudinga atskirti aprašomąsias ir nurodomąsias API. A aprašomoji API apibūdina kodo realų veikimą, o a receptinis API aprašoma, kaip kodas turėtų funkcija.

Abu šie stiliai yra naudingi ir abu yra labai patobulinti naudojant API struktūrizuotą standartinį formatą. Kaip taisyklė, API naudojimas kuriant kodą yra nurodomasis vartojimas, o kodo naudojimas „Java“ API apibrėžimo išvedimui yra aprašomasis naudojimas.

Reikalavimų rinkimas naudojant „Java“ API

Koncepciniame ir įgyvendinimo spektre reikalavimų rinkimas yra visiškai per koncepcinę pusę. Tačiau net ir konceptualiame „app dev“ etape galime pradėti galvoti apie API.

Tarkime, kad jūsų projektuojama sistema susijusi su kalnų dviračiais - konstrukcijomis, dalimis ir pan. Kaip kūrėjas, orientuotas į objektą, pirmiausia turėtumėte kalbėtis su suinteresuotosiomis šalimis apie reikalavimus. Po to gana greitai pagalvotumėte apie abstraktą „BikePart“ klasė.

Tada pagalvotumėte per internetinę programą, kuri valdytų įvairius dviračių dalių objektus. Netrukus susitiksite su bendrais reikalavimais valdyti tas dviračių dalis. Čia pateikiamas momentinis vaizdo įrašas reikalavimų etapas dviračių dalių programos dokumentų:

  • Programa turi sugebėti sukurti dviračio dalies tipą (pavarų perjungiklį, stabdžius ir kt.).
  • Įgaliotas vartotojas turi sugebėti išvardyti, sukurti ir aktyvinti dalių tipą.
  • Neteisėtas vartotojas turi galėti išvardyti aktyvių dalių tipus ir peržiūrėti atskirų sistemos dalių egzempliorių sąrašus.

Jau galite pamatyti, kaip formuojasi paslaugų kontūrai. Turėdami omenyje galimas API, galite pradėti braižyti tas paslaugas. Kaip pavyzdį, pateikiame dalinį „RESTful CRUD“ paslaugų sąrašą dviračių dalių tipams:

  • Sukurti dviračio dalies tipą: PUT / part-type /
  • Atnaujinti dviračio dalies tipą: POST / part-type /
  • Išvardykite dalių tipus: GET / part-type /
  • Gaukite detalių tipų informaciją: GET / part-type /: id

Atkreipkite dėmesį, kaip CRUD tarnybos pradeda užsiminti apie įvairių paslaugų ribų formą. Jei kuriate mikropaslaugų stilių, jau galite pamatyti tris dizaino paslaugas:

  • Dviračių dalių paslauga
  • Dviračio dalies tipo paslauga
  • Autentifikavimo / autorizavimo paslauga

Nes aš galvoju apie API kaip susijusių subjektų ribos, Manau, kad šiame sąraše esančios mikro paslaugos yra API paviršiai. Kartu jie siūlo didelę programos architektūros vaizdą. Išsami informacija apie pačias paslaugas taip pat aprašoma taip, kaip naudosite techninėms specifikacijoms, kurios yra kitas programinės įrangos kūrimo gyvavimo ciklo etapas.

Techninė specifikacija su „Java“ API

Jei įtraukėte API dėmesį kaip į reikalavimų rinkimo dalį, tada jau turite gerą techninių specifikacijų sistemą. Kitas etapas yra technologijos kamino, kurį naudosite specifikacijai įgyvendinti, pasirinkimas.

Tiek daug dėmesio skiriant RESTful API kūrimui, kūrėjai sugėdina turtus, kai reikia įgyvendinti. Nepriklausomai nuo pasirinkto kamino, šiame etape dar labiau papildžius API, suprasite daugiau programos architektūrinių poreikių. Parinktys gali apimti VM (virtuali mašina), skirtą programai priglobti, duomenų bazę, galinčią valdyti jūsų teikiamų duomenų kiekį ir tipą, ir debesies platformą „IaaS“ arba „PaaS“ diegimo atveju.

API galite naudoti norėdami nukreipti „žemyn“ link schemų (arba „NoSQL“ dokumentų struktūrų) arba „aukštyn“ link vartotojo sąsajos elementų. Kurdami API specifikaciją, greičiausiai pastebėsite šių problemų sąveiką. Visa tai yra gerai ir dalis proceso. API tampa centrine gyvenamąja vieta, kur galima užfiksuoti šiuos pokyčius.

Kitas rūpestis, kurį reikia nepamiršti, yra tai, kurias viešąsias API jūsų sistema pateiks. Suteikite papildomų minčių ir atsargumo. Viešosios API kartu su pagalba kuriant pastangas yra paskelbta sutartis, kurią išorinės sistemos naudoja sąsajai su jūsų.

Viešosios debesies API

Apskritai API apibrėžia programinės įrangos sistemos sutartį, suteikiant žinomą ir stabilią sąsają, pagal kurią galima programuoti kitas sistemas. Tiksliau sakant, viešoji debesies API yra viešoji sutartis su kitomis organizacijomis ir programuotojais, kuriančiais sistemas. Pavyzdžiai yra „GitHub“ ir „Facebook“ API.

„Java“ API dokumentavimas

Šiame etape norėsite pradėti fiksuoti savo API oficialioje sintaksėje. 1 lentelėje išvardijau keletą žinomų API standartų.

API formatų palyginimas

 
vardasSantraukaŽvaigždės „GitHub“URL
„OpenAPI“JSON ir YML palaikomas API standartas, kilęs iš „Swagger“ projekto, apima įvairius įrankius „Swagger“ ekosistemoje.~6,500//github.com/OAI/OpenAPI-Specification
RAMLYML pagrįstos specifikacijos, kurias daugiausia palaiko „MuleSoft“~3,000//github.com/raml-org/raml-spec
API „BluePrint“API dizaino kalba, naudojant sintaksę, panašią į „MarkDown“~5,500//github.com/apiaryio/api-blueprint/

Praktiškai bet koks formatas, kurį pasirinkote dokumentuodami savo API, turėtų būti gerai. Tiesiog ieškokite struktūrizuoto, oficialių specifikacijų ir gerų įrankių formato, kuris, atrodo, bus aktyviai palaikomas ilgą laiką. Tiek RAML, tiek „OpenAPI“ atitinka tą sąskaitą. Kitas tvarkingas projektas yra „API Blueprint“, kuriame naudojama žymėjimo sintaksė. Šiame straipsnyje mes naudosime „OpenAPI“ ir „Swagger“.

„OpenAPI“ ir „Swagger“

„OpenAPI“ yra JSON formatas, apibūdinantis REST pagrįstas API. „Swagger“ pradėjo veikti kaip „OpenAPI“, tačiau tapo „OpenAPI“ formato įrankių rinkiniu. Šios dvi technologijos gerai papildo viena kitą.

Pristatome „OpenAPI“

Šiuo metu „OpenAPI“ yra labiausiai paplitęs pasirinkimas kuriant RESTful apibrėžimus. Įtraukianti alternatyva yra RAML (RESTful API Markup Language), paremta YAML. Aš asmeniškai supratau, kad „Swagger“ įrankiai (ypač vizualaus dizainerio) yra labiau nugludinti ir be klaidų nei „RAML“.

„OpenAPI“ naudoja daugumai kūrėjų pažįstamą JSON sintaksę. Jei nenorite apkrauti JSON, galite naudoti UI, kad būtų lengviau dirbti. 2 dalyje pateikiami vartotojo sąsajos, skirtos RESTful apibrėžimams.

1 sąrašas yra „OpenAPI“ JSON sintaksės pavyzdys.

Sąrašas 1. „OpenAPI“ apibrėžimas paprastam „BikePart“

 "paths": {"/ part-type": {"get": {"description": "Gauna visus sistemoje galimus dalių tipus", "operationId": "getPartTypes", "produkcija": ["programa / json "]," responses ": {" 200 ": {" description ":" Gets the BikeParts "," schema ": {" type ":" array "," items ": {" $ ref ":" # / definitions / BikePart "}}}}}}} 

Šis apibrėžimas yra toks glaustas, kad praktiškai tai yra „Spartan“, kuris kol kas yra gerai. Ateityje yra daug galimybių padidinti API apibrėžimo detalumą ir sudėtingumą. Netrukus parodysiu jums išsamesnę šio apibrėžimo iteraciją.

Kodavimas iš „Java“ API

Reikalavimų rinkimas baigtas ir pagrindinė programa buvo išleista, o tai reiškia, kad esate pasirengęs linksmai daliai --- koduoti! Oficialus „Java“ API apibrėžimas suteikia jums keletą privalumų. Viena vertus, jūs žinote, kokius galinius taškus programinės įrangos ir išorės kūrėjams reikia sukurti ir koduoti. Net jei esate vieno iš jų komanda, pradėdami koduoti greitai pamatysite API pagrįsto požiūrio vertę.

Kuriant programą taip pat pamatysite, kaip naudinga API, kad užfiksuotumėte pirmyn ir atgal vykstančias plėtros ir verslo derybas. API įrankių naudojimas pagreitins kodo pakeitimų taikymą ir dokumentavimą.

Detalesnėms specifikacijoms ir tikram kodavimui gali prireikti išsamesnės informacijos nei trumpas apibrėžimas 1 sąraše. Be to, didesnėms ir sudėtingesnėms sistemoms gali būti naudingos galimybės, kurios bus keičiamos, pavyzdžiui, dokumentų nuorodos. 2 sąraše pateikiamas išsamesnis „BikePart“ API pavyzdys.

Sąrašas 2. Detalių pridėjimas prie „BikePart“ API apibrėžimo

 "paths": {"/ part-type": {"get": {"description": "Gauna visus sistemoje galimus dalių tipus", "operationId": "getPartTypes", "produkcija": ["programa / json "]," parametrai ": [{" pavadinimas ":" riba "," in ":" užklausa "," aprašymas ":" maksimalus grąžintinų rezultatų skaičius "," būtinas ": klaidingas," tipas ": "sveikasis skaičius", "formatas": "int32"}], "atsakymai": {"200": {"description": "dalies tipo sąrašas", "schema": {"type": "masyvas", "elementai ": {" $ ref ":" # / definitions / PartType "}}}," default ": {" description ":" netikėta klaida "," schema ": {" $ ref ":" # / definitions / Error " }}}}