Mens du fikk kaffen din, endret Java-applikasjonsutviklingen -en gang til.
I en verden drevet av rask endring og innovasjon, er det ironisk at API-er gjør comeback. Som kodingsekvivalenten til New York Citys t-banesystem i alderen med autonome biler, er API-er gammel teknologi- gammel, men uunnværlig. Det som er interessant er hvordan denne usynlige, daglige IT-arkitekturen blir tenkt på nytt og brukt i dagens teknologitrender.
Mens APIer er overalt, har de blitt spesielt fremtredende i sin eksterne inkarnasjon som RESTful-tjenester, som er ryggraden i skyutplasseringer. Skytjenester er offentlige APIer, som er preget av endepunkter som er offentlige og publiserte strukturer. Cloud-baserte apper trender også mot mikrotjenester, som er uavhengige, men relaterte distribusjoner. Alle disse faktorene øker prominensen til API-er.
I denne todelte opplæringen lærer du hvordan du setter Java APIer i hjertet av design- og utviklingsprosessen, fra konsept til koding. Del 1 starter med en oversikt og introduserer deg for OpenAPI, også kjent som Swagger. I del 2 lærer du hvordan du bruker Swaggers API-definisjoner til å utvikle en Spring Web MVC-app med en Angular 2-frontend.
Hva er en Java API?
API-er er så vanlig i programvareutvikling at det noen ganger antas at programmerere bare vet hva de er. I stedet for å stole på osmose, la oss ta et øyeblikk å pakke ut det vi mener når vi snakker om API-er.
Generelt kan vi si at API-er setter og administrerer grensene mellom systemer.Først, API står for "applikasjonsprogrammeringsgrensesnitt." En APIs rolle er å spesifisere hvordan programvarekomponenter samhandler. Hvis du er kjent med objektorientert programmering, kjenner du API-er i deres inkarnasjon som grensesnittene og klassene som brukes for å få tilgang til underliggende funksjoner på språket, eller som det offentlige ansiktet til tredjepartsbiblioteker og OS-muligheter.
Generelt kan vi si at API-er setter og administrerer grensene mellom systemer, som vist i figur 1.
Matthew Tyson Så hvor gir det oss API-drevet utvikling?
Java APIer for cloud computing, mikrotjenester og REST
Programmering med API-er kommer i forgrunnen med den moderne web-API: a nettverkseksponert API (NEA), hvor grensen mellom systemene er "over ledningen." Disse grensene er allerede sentrale i nettapper, som er det vanlige kontaktpunktet mellom front-end-klienter og back-end-servere. Skyrevolusjonen har eksponentielt økt viktigheten av Java APIer.
Enhver programmeringsaktivitet som krever forbruk av skytjenester (som i utgangspunktet er offentlige API-er) og dekonstruksjon av systemer til mindre, uavhengige, men relaterte distribusjoner (også kjent som mikrotjenester), er avhengig av API-er. Nettverkseksponerte API-er er ganske enkelt mer universelle, lettere oppnådd og lettere endret og utvidet enn tradisjonelle APIer. Den nåværende arkitektoniske trenden er å utnytte disse funksjonene.
Mikrotjenester og offentlige API-er vokser fra røttene til serviceorientert arkitektur (SOA) og software-as-a-service (SaaS). Selv om SOA har vært en trend i mange år, har bred adopsjon blitt hindret av SOAs kompleksitet og overhead. Bransjen har brukt RESTful APIer som de facto-standarden, og gir akkurat nok struktur og konvensjon med mer fleksibilitet i den virkelige verden. Med REST som bakgrunn kan vi lage formelle API-definisjoner som beholder menneskelig lesbarhet. Utviklere lager verktøy rundt disse definisjonene.
Generelt er REST en konvensjon for å kartlegge ressurser til HTTP-baner og tilhørende handlinger. Du har sannsynligvis sett på disse som HTTP GET- og POST-metoder. Det viktigste er å bruke HTTP som standard, og legge konvensjonelle kartlegginger på toppen av det for forutsigbarhet.
Bruker Java APIer i design
Du kan se viktigheten av API-er, men hvordan vil du bruke dem til din fordel?
Å bruke Java API-definisjoner for å drive design- og utviklingsprosessen er en effektiv måte å strukturere tankene dine om IT-systemer på. Ved å bruke Java API-definisjoner helt fra begynnelsen av programvarens utviklingslivssyklus (konsept og kravinnsamling) vil du lage en verdifull teknisk gjenstand som er nyttig helt frem til distribusjon, samt for løpende vedlikehold.
La oss vurdere hvordan Java API-definisjoner bygger bro over konsept- og implementeringsstadiene i utviklingen.
Beskrivende vs reseptive API-er
Det er nyttig å skille mellom beskrivende og reseptive API-er. EN beskrivende API beskriver måten koden faktisk fungerer på, mens a forskrivende API beskriver hvordan koden bør funksjon.
Begge disse stilene er nyttige, og begge forbedres sterkt ved å bruke et strukturert standardformat for API-definisjon. Som en tommelfingerregel er det å bruke API for å drive opprettelse av kode en forskriftsmessig bruk, mens bruk av koden for å sende ut Java API-definisjonen er en beskrivende bruk.
Krav som samles med Java APIer
På det konseptuelle til implementeringsspekteret er kravsamling langt over på konseptet. Men selv i den konseptuelle fasen av apputvikling, kan vi begynne å tenke i form av APIer.
Si at systemet ditt i design har å gjøre med terrengsykler - konstruksjon, deler og så videre. Som en objektorientert utvikler vil du begynne med å snakke med interessenter om krav. Ganske raskt etter det, ville du tenkt på et abstrakt BikePart klasse.
Deretter vil du tenke gjennom webapplikasjonen som ville administrere de forskjellige sykkeldelene. Snart ville du komme til vanlige krav for å administrere disse sykkeldelene. Her er et øyeblikksbilde av kravfase av dokumentasjon for en sykkeldel-app:
- Søknaden må kunne lage en type sykkeldel (girskifte, brems osv.).
- En autorisert bruker må kunne liste, opprette og gjøre en deltype aktiv.
- En uautorisert bruker må være i stand til å liste opp aktive deltyper, og se lister over individuelle deltypeforekomster i systemet.
Allerede kan du se omrissene av tjenester som tar form. Med eventuelle API-er i tankene, kan du begynne å tegne disse tjenestene. Som et eksempel, her er en delvis oppføring av RESTful CRUD-tjenester for sykkeldelstyper:
- Lag sykkeldeltype:
PUT / del-type / - Oppdater type sykkeldeler:
POST / del-type / - Liste deltyper:
FÅ / del-type / - Få detaljert delen:
GET / del-type /: id
Legg merke til hvordan CRUD-tjenestene begynner å antyde formen til ulike servicegrenser. Hvis du bygger i en mikrotjenestestil, kan du allerede se tre mikrotjenester som kommer fra designet:
- En sykkel-del service
- En sykkel del-type tjeneste
- En godkjenning / autorisasjonstjeneste
Fordi jeg tenker på APIer som grenser for relaterte enheterJeg anser mikrotjenestene fra denne listen for å være API-overflater. Sammen gir de et stort bilde av applikasjonsarkitekturen. Detaljer om selve tjenestene er også beskrevet på en måte som du vil bruke til den tekniske spesifikasjonen, som er neste fase av programvarens utviklingssyklus.
Teknisk spesifikasjon med Java APIer
Hvis du har tatt med API-fokuset som en del av kravinnsamlingen, har du allerede et godt rammeverk for teknisk spesifikasjon. Neste trinn er å velge teknologibakken du vil bruke til å implementere spesifikasjonen.
Med så mye fokus på å bygge RESTful APIer, har utviklere en forlegenhet av rikdom når det gjelder implementering. Uansett hvilken stabel du velger, vil utbyggingen av API-en enda lenger på dette stadiet øke din forståelse av appens arkitektoniske behov. Alternativene kan omfatte en virtuell maskin (virtuell maskin) for å være vert for applikasjonen, en database som kan administrere volumet og typen data du serverer, og en skyplattform i tilfelle IaaS- eller PaaS-distribusjon.
Du kan bruke API-en til å kjøre "nedover" mot skjemaer (eller dokumentstrukturer n NoSQL), eller "oppover" mot UI-elementer. Når du utvikler API-spesifikasjonen, vil du sannsynligvis merke et samspill mellom disse bekymringene. Dette er alt bra og en del av prosessen. API-et blir et sentralt levende sted for å fange opp disse endringene.
En annen bekymring å huske på er hvilke offentlige APIer systemet ditt vil eksponere. Gi ekstra tanke og omsorg til disse. I tillegg til å bistå i utviklingsarbeidet, fungerer offentlige APIer som den publiserte kontrakten som eksterne systemer bruker for å grensesnitt med din.
Offentlige sky-APIer
Generelt definerer API-er kontrakten til et programvaresystem, og gir et kjent og stabilt grensesnitt som andre programmer kan programmeres mot. Spesielt er en offentlig sky API en offentlig kontrakt med andre organisasjoner og programmerere som bygger systemer. Eksempler er GitHub og Facebook APIer.
Dokumentere Java API
På dette stadiet vil du begynne å fange API-ene dine i formell syntaks. Jeg har listet noen få fremtredende API-standarder i tabell 1.
Sammenligning av API-formater
| Navn | Sammendrag | Stjerner på GitHub | URL |
|---|---|---|---|
| OpenAPI | JSON og YML-støttet API-standard stammer fra Swagger-prosjektet, inneholder en rekke verktøy i Swagger-økosystemet. | ~6,500 | //github.com/OAI/OpenAPI-Spesifikasjon |
| RAML | YML-basert spesifikasjon støttet hovedsakelig av MuleSoft | ~3,000 | //github.com/raml-org/raml-spec |
| API BluePrint | Et API-designspråk som bruker MarkDown-lignende syntaks | ~5,500 | //github.com/apiaryio/api-blueprint/ |
Så å si ethvert format du velger for å dokumentere API-en din, bør være i orden. Bare se etter et format som er strukturert, har en formell spesifikasjon og godt verktøy rundt det, og ser ut til at det vil bli aktivt opprettholdt på lang sikt. Både RAML og OpenAPI passer til regningen. Et annet pent prosjekt er API Blueprint, som bruker markdown-syntaks. For eksempler i denne artikkelen skal vi bruke OpenAPI og Swagger.
OpenAPI og Swagger
OpenAPI er et JSON-format for beskrivelse av REST-baserte APIer. Swagger startet som OpenAPI, men har utviklet seg til et sett med verktøy rundt OpenAPI-formatet. De to teknologiene utfyller hverandre godt.
Vi presenterer OpenAPI
OpenAPI er for tiden det vanligste valget for å lage RESTful-definisjoner. Et overbevisende alternativ er RAML (RESTful API Markup Language), som er basert på YAML. Personlig har jeg funnet verktøyet i Swagger (spesielt den visuelle designeren) mer polert og feilfritt enn i RAML.
OpenAPI bruker JSON-syntaks, som er kjent for de fleste utviklere. Hvis du helst ikke vil anstrenge øynene dine for å analysere JSON, er det brukergrensesnitt som gjør det lettere å jobbe med det. Del 2 introduserer brukergrensesnitt for RESTful-definisjoner.
Oppføring 1 er et eksempel på OpenAPIs JSON-syntaks.
Oppføring 1. OpenAPI-definisjon for en enkel BikePart
"stier": {"/ part-type": {"get": {"description": "Henter alle deltyper som er tilgjengelige i systemet", "operationId": "getPartTypes", "produserer": ["applikasjon / json "]," response ": {" 200 ": {" description ":" Henter BikeParts "," schema ": {" type ":" array "," items ": {" $ ref ":" # / definisjoner / BikePart "}}}}}}} Denne definisjonen er så kortfattet at den praktisk talt er spartansk, noe som er greit for nå. Det er god plass til å øke detaljene og kompleksiteten i API-definisjonen fremover. Jeg vil vise deg en mer detaljert iterasjon av denne definisjonen om kort tid.
Koding fra Java API
Kravsamling er ferdig og den grunnleggende appen er spesifisert, noe som betyr at du er klar for den morsomme delen --- koding! Å ha en formell Java API-definisjon gir deg noen tydelige fordeler. For det første vet du hvilke endepunkter back-end og front-end-utviklere trenger å opprette og kode mot, henholdsvis. Selv om du er et team av en, vil du raskt se verdien av en API-drevet tilnærming når du begynner å kode.
Når du bygger ut applikasjonen, vil du også se verdien av å bruke API-er for å fange frem og tilbake forhandlinger mellom utvikling og virksomhet. Bruk av API-verktøy vil øke hastigheten på både bruk og dokumentasjon av kodeendringer.
Mer detaljerte spesifikasjoner og faktisk koding kan kreve større detaljer enn den kortfattede definisjonen i oppføring 1. I tillegg kan større og mer komplekse systemer fortjene muligheter som skaleres, som dokumentreferanser. Oppføring 2 viser et mer konkret eksempel på BikePart API.
Oppføring 2. Legge til detaljer i BikePart API-definisjonen
"stier": {"/ part-type": {"get": {"description": "Henter alle deltyper som er tilgjengelige i systemet", "operationId": "getPartTypes", "produserer": ["applikasjon / json "]," parameters ": [{" name ":" limit "," in ":" query "," description ":" maksimalt antall resultater som skal returneres "," required ": false," type ": "heltall", "format": "int32"}], "response": {"200": {"description": "part-type listing", "schema": {"type": "array", "items ": {" $ ref ":" # / definitions / PartType "}}}," default ": {" description ":" uventet feil "," schema ": {" $ ref ":" # / definitions / Error " }}}} 
