REST API Utviklingstips og beste fremgangsmåter - Del 1

Introduksjon og planlegging

Dette er den første i en serie med tre innlegg på REST API-er.

• Del 1: Introduksjon og planlegging
• Del 2: Skjemaforslag, vanlige feil og avskrivninger
• Del 3: Dokumentasjonstips og gå videre enn det grunnleggende

INTRODUKSJON

REST APIer er overalt i disse dager. Hvis du utvikler nettverksaktiverte applikasjoner, er sjansen stor for at du har konsumert minst en i koden, og muligens at du leser dette fordi du er i ferd med å skrive en egen.

Hva denne serien er og hva den ikke er

Denne postserien er ikke en introduksjon til REST. Det forutsetter at du har en klar forståelse av hva REST er og hva den har som mål å oppnå. Det er heller ikke på noen måte en omfattende Best Practices-artikkel om design og utvikling av Web API. Det er mange av de som allerede er tilgjengelige på nettet, og jeg vil foreslå at du leser så mange du kan.

Det det meste er, er en liste over veldig vanlige og ofte oversett feil folk gjør når de designer og implementerer REST APIer. Jeg vet ikke bare fordi jeg har møtt dem i andre menneskers API-er, men fordi jeg har laget noen av dem selv. :)

Hvorfor dette ble skrevet

I en perfekt verden er det første noen bør gjøre rett etter å ha utviklet et REST API, skrive en klientapplikasjon for det. Jeg snakker ikke om et brukergrensesnitt med en liste over endepunkter som folk kan ringe, snarere enn et faktisk bruksmål for API-et. Det er ingenting mer å åpne for å avsløre ineffektivitetene i skapelsen din, enn å faktisk måtte bruke den ordentlig selv. Jeg vet dette, fordi jeg har måttet gjøre det mange ganger.

Verden vår er selvfølgelig ikke perfekt, og det meste av tiden må en back-end-utvikler gå videre til andre ting etter at de er ferdige med API-implementeringen, men bare til API-forbrukerne må innkalle ham tilbake for å sone for hans synder. Jeg har vært i den ulykkelige posisjonen mange ganger også, så forhåpentligvis vil mine feil og tips hjelpe deg med å spare tid - slik at du ikke trenger å komme tilbake til API-koden din før det er på tide å legge til nye funksjoner.

PLANLEGGER

Bilde gitt av Dan Bickell

1. Før du begynner

Studer så mange REST API design og utviklingsdokumenter og bøker som du kan finne! Jeg vil ikke nevne vanlige tips her, for eksempel å bruke substantiv i stedet for verb-URI-er (ups, det har jeg nettopp gjort ...) osv., Men det er fordi jeg antar at du allerede har lest om dem et annet sted.

Vurder alternativer

REST er ganske populært som et paradigme, men det kommer i mange smaker. Før du fortsetter videre, bør du ta en titt på så mange av dem du kan. Mens du er inne på det, ikke glem å sjekke GraphQL - en helt annen tilnærming, som ikke bare virker bra for visse brukstilfeller, men også brukes av Facebook (som utviklet den) og GitHubs nye v4 API.

Se hva andre har gjort

Sjekk ut og prøv faktisk å bruke så mange populære API-er, fra anerkjente organisasjoner, som du kan. Her er noen få for å komme i gang: GitHub, Stripe, Twitter, PayPal

2. Stiftelsen

Anta ikke at API-en din vil forbli liten - det skjer nesten aldri. Selv om du er den eneste som bruker den til din egen klient-app, trenger du ganske snart et ekstra sluttpunkt, paginering, analyse, en testmodus og hvem vet hva annet, og det er til og med før appen din blir populær og andre mennesker starter ber om tilgang til API ...

OK - kanskje det er en strekning; men som det vanligvis skjer i programvareutvikling, hvis du ikke legger et solid grunnlag tidlig, vil du betale for det på lang sikt. Siden APIer må være konsistente for å være lett forbrukbare, vil det å prøve å legge til funksjoner til dem ved hjelp av duct-tape ikke bare gjøre ting vanskeligere for deg, men også for kundene dine.

Videre, jo bedre blir du med å holde ting rene, jo mindre tid tar det å fullføre dem og ganske snart ...

3. Spesifikasjon

Å snakke om et sterkt fundament; prøv å lage spesifikasjonen for API før du begynner å skrive kode. Jeg vet at det høres kjedelig ut hvis du ikke har gjort det før, men det lønner seg på sikt og sparer deg for mye tid og problemer.

OpenAPI-spesifikasjonen (OAS - tidligere Swagger) ser ut til å være den mest populære veien å gå for øyeblikket, ettersom flere og flere organisasjoner og alternativer konvergerer det. Alternativt er Postman et flott API-utviklingsmiljø, men det er bare gratis for enkeltpersoner eller små team av utviklere.

Jeg vil sterkt anbefale å ikke ignorere dette tipset, med mindre du utvikler en liten intern API som bare du vil konsumere.

4. Versjonering

Jeg vil ikke fokusere på forskjellige versjonsmetoder i dette innlegget, siden det er mange dedikerte ressurser om dette emnet på nettet. Jeg vil bare prøve å fremheve hvor viktig det er at du velger en robust versjonstilnærming og følger den religiøst. Jeg vil også presentere en tilnærming som har tjent meg godt gjennom årene.

Hvorfor det er viktig

En sterk versjonstilnærming gir deg ro i forbrukerne (og derfor sluttbrukere) fordi det forhindrer at API-endringer forstyrrer funksjonaliteten til eksisterende klientapplikasjoner. Selv når klientapplikasjoner selv er utviklet av den samme utvikleren eller den samme organisasjonen som API, er det mange scenarier der utdaterte klienter fremdeles kan være i bruk på det tidspunktet en API-oppdatering er tilgjengelig.

En veldig vanlig forekomst av dette fenomenet er mobile eller desktop OS-klientapplikasjoner, der utviklerne sjelden har full kontroll over oppdateringssyklusen. Uansett hvor gode og automatiserte klientoppdateringsmekanismer er, kan du nesten aldri være 100% sikker på at brukerne dine kjører den nyeste versjonen av klientappene dine.

iOS har en veldig pålitelig automatisk oppdateringsmekanisme for applikasjoner som er aktivert som standard, men avhengig av brukerens preferanser og nettverksstatus, kan det hende at enheten deres ikke har hatt en sjanse til å oppdatere klientappen din neste gang den kjøres. Det samme er tilfelle for nyere versjoner av Android, mens det er enda mer sannsynlig at eldre versjoner henger langt etter i appoppdateringer.

Desktop-apper, derimot, gir kanskje ikke en automatisk oppdateringsmekanisme - men de er mest av tiden opt-in, og det er alltid tilfeller (for eksempel bedriftsmiljøer) som ikke tillater umiddelbare oppdateringer. Til og med nettleserklienterapper kan (og i de fleste tilfeller bør) kobles fra deres backend og har derfor en helt annen utgivelsessyklus enn API-en.

Kommuniser endringer til forbrukerne dine

Selv om du har det perfekte API med det beste versjonssystemet på plass, betyr det ingenting om forbrukerne dine ikke er klar over det fulle potensialet. Å kommunisere endringer og nye funksjoner er avgjørende for at brukerne dine skal kunne dra full nytte av dem. Enda viktigere er å advare brukerne dine tidlig nok om aspekter som kommer til å bli utdatert eller fjernet, slik at de har tid nok til å oppdatere, teste og sende nye versjoner av kundene sine.

Å holde en oppdatert dokumentasjon og slippe detaljerte endringer for hver versjon er av største betydning og bør være en del av utviklingssyklusen din.

Major / mindre versjon tilnærming

En versjonstilnærming som jeg har satt stor pris på gjennom årene er et større / mindre versjonsskjema. API-en din er preget av et stort versjonsnummer, som (hvis du gjør ting riktig) bare oppdateres når det er ødelagte endringer, og et mindre versjonsnummer, som oppdateres når det er små trinnvise tillegg.

Sett fra en annen vinkel, garanterer hver hovedversjon at strukturen i API-ressursene og skjemaet ikke går i stykker i løpet av levetiden, uansett hvor mange mindre versjoner som blir gitt ut i mellomtiden. Mindre versjoner er bakoverkompatible.

Det er vanlig at hovedversjonen er en del av grunnadressen til API (f.eks. Https://api.myserver.com/v1/endpoint) og den mindre versjonen kan velges via en forespørselstittel. Når forespørselsoverskriften ikke er gitt, brukes den siste mindre versjonen. Det er mange populære API-er som følger denne tilnærmingen, og min favoritt er Stripe (som bruker utgivelsesdatoer for mindre versjoner).

Selv om jeg vil nevne denne tilnærmingen igjen når jeg snakker om oppdateringer til API-en i de følgende seksjonene, er det opp til deg å velge ditt eget formelle versjonssystem som fungerer best for dine behov. Bare husk at når du først gjør det, må du forplikte deg til det.

5. Testing

Dette er bra når du ikke er i produksjon

Som en integrert del av programvareutviklingsprosessen generelt er testing avgjørende for API-en din. Siden APIer vanligvis fungerer som bindeleddet mellom sannhetskilden som er serveren og en eller flere klientapplikasjoner, må de være pålitelige under alle omstendigheter og har ikke råd til å gå i produksjon ødelagt på noen måte. Siden de vanligvis er utsatt for nettet og derfor er sårbare for et stort antall risikoer, må de testes grundig for et stort antall vanlige og ikke-så-vanlige scenarier.

Manuell testing ved å ringe sluttpunktene dine via verktøy som Swagger, Postman eller REST-konsoll, kan bare hjelpe deg i løpet av de første babytrinnene i utviklingen, når du fremdeles tester de forskjellige grunnleggende funksjonene. Å opprettholde en serie automatiserte tester fra tidlig, gjør en verden av forskjell for kvaliteten på det ferdige produktet.

På grunn av sin natur er APIer ideelle kandidater for funksjonell testing. Enhetstesting av deres interne implementering er veldig viktig (som for enhver annen programvare), men, etter min mening, funksjonell testing av en API og likning av den til en svart boks gir mye mer verdi for tiden du vil bruke på den.

Vedlikehold av en testdatabase som du kan sette opp og rive mens du tester er en viktig del av prosessen. Fortsett å legge til data som har bidratt til tidligere problemer (observert under utvikling eller rapportert av forbrukerne dine), og berik testpakken din med regresjonstester for å sikre deg at du ble kvitt disse feilene en gang for alle.

Ikke anta at valideringen av inndataparametere er fullført før du har testet selv de underligste sakene (ikke glem at klientappene dine kan være ganske buggy selv). Til slutt kan du investere tid i en skikkelig loggeinfrastruktur for å fange de få gjenværende runtime-feilene, observere forbrukeratferd og bruke denne informasjonen til å lage enda flere testscenarier.

6. Distribusjon

Som du kanskje allerede har lagt merke til (eller vil merke når du fortsetter å lese), fokuserer dette innlegget mye på hvordan du oppretter et API som ikke ødelegger ting. Den mest skremmende fasen for å ødelegge ting i nesten alle programvareprodukter er selvfølgelig distribusjon.

I de fleste tilfeller, hvis du har testet og versjonert riktig, er sjansen for å få et problem under utplasseringen veldig lav. her er imidlertid et par tips som kan være til hjelp.

Frakoble alt

Her er et veldig vanlig scenario:

APIen din gir data til et par B2B-klienter utviklet av eksterne organisasjoner, serverer et par mobilapper og en webapp utviklet av din egen organisasjon, og er en integrert del av en serverapplikasjon - som også tilfeldigvis er tilgjengelig via nettet , til administrasjonsformål.

Det kan høres komplisert ut, men jeg har sett det mange ganger tidligere i enklere eller mer sammensatte varianter. Hovedpoenget her er at API, selv om det er hjørnesteinen i en organisasjon, ofte er tett koblet med minst en server-app som har andre ansvarsområder.

Det betyr at når det er på tide å oppdatere serverappen, hvis noe går i stykker, er det en god sjanse for at API også vil bryte. Hvis det skjer, vil API-en få alle forbrukerne med seg, og til slutt vil sluttbrukernes vrede komme over selskapet.

Å bry deg om brukerne dine er det siste du ønsker

En annen mangel på tett kobling i denne sammenhengen er at utgivelsessyklusen til en app påvirker alle de andre. Det vil kreve kompleks planlegging og orkestrering av distribusjoner. Videre gir det ingen mening fra et forretningsmessig synspunkt (hver app skal utgis i sin egen god tid - uten å påvirke resten).

Hvis API-en din og resten av appene dine er utviklet som uavhengige moduler i infrastrukturen din, forsvinner alt dette. Noen vil kanskje hevde at det å ha flere separate moduler betyr flere feilpunkter, men det kan løses med riktig versjon og testing. Videre, selv om den nye versjonen av API-en din bryter ved utplasseringen, vil teamet ditt være det første som vet det. I dette tilfellet, hvis ikke noe bedre kan gjøres, kan du alltid utsette kundenes utgivelser i et par dager til du er sikker på at alt fungerer som det skal.

En farlig sak du må beskytte deg for med streng testing, er når den nye versjonen av serverappen din bryter den eksisterende versjonen av API-en din. Igjen, den eneste måten å unngå dette på er (selvfølgelig) gjennom en streng utviklingsprosess med riktig versjonering og testing. Å behandle alle delene av infrastrukturen som forskjellige moduler oppmuntrer den tilnærmingen ytterligere.

7. (Grasiøs) avskrivning

Når appen din modnes på et tidspunkt, er det uunngåelig at du må avskrive den nåværende hovedversjonen av API til fordel for en ny. Klientapper som fremdeles er under utvikling, må også oppgradere til den nye versjonen, men det kan ta tid.

Dessuten er det tilfeller hvor til og med øyeblikkelig handling fra utviklerne ikke betyr umiddelbare oppdateringer til klientapplikasjonene. Selv om oppdaterte versjoner av webapper kan gjøres tilgjengelige for sluttbrukere så snart de er utgitt, har eldre versjoner av mobile og native OS-apper en tendens til å holde seg lenge. Noen brukere forstår ikke (eller er ikke engang klar over) oppdateringsprosessen for apper på telefonen eller datamaskinen deres. Hvis disse appene plutselig begynner å fungere, kan brukernes respons være å bare slutte å bruke dem.

Avskrivning av en større API-versjon skal ikke bety avbrudd i tjenesten. Den utdaterte versjonen bør fortsette å fungere nøyaktig som den gjorde, i en periode (så lenge som mulig) som vil bli kommunisert tydelig og gjentatte ganger (når den nærmer seg slutten) til forbrukerne dine. Ideelt sett skal eldre versjoner av API-en din aldri slutte å fungere, med mindre de utgjør en sikkerhetsrisiko, eller på annen måte skader din støtte.

8. Ofte ignorert god praksis

Du kan bruke flertall eller entallformer for ressurser, men ikke begge deler

/ biler er bra, og det samme er / bil, men du kan ikke bruke begge deler. Velg en form og hold deg til den i hele API-en. Hvis du ikke gjør det, vil du forvirre forbrukerne dine og kanskje til og med dine egne utviklere eller deg selv i fremtiden.

Returner oppdaterte objekter i PUT- og PATCH-svar

Etter en vellykket forespørsel via PUT- eller PATCH-verb, trenger klienten vanligvis å vite tilstanden til den oppdaterte ressursen. Siden det er ganske mulig at flere klienter kan oppdatere den samtidig, er dette den eneste måten å holde hver enkelt informert om tilstanden til ressursen i det øyeblikket oppdateringen skjedde.

Informasjonskapsler og PHPSESSIONID

Denne er veldig vanlig i PHP-utviklede applikasjoner. API-en bruker sitt eget tilpassede autentiseringsmerke, men ukjent for utvikleren som bruker PHPs standardhåndtering, inkluderer alle svar også den fryktede PHPSESSIONID-informasjonskapselen! Dette forårsaker alle slags feil i det lange løp, fordi ingen (inkludert utvikleren) blir informert om informasjonskapselen, fordi ingen tror de legger den der.

Informasjonskapsler er generelt ikke eksplisitt forbudt av REST. De kan forårsake problemer hvis de brukes feil (for eksempel hvis du prøver å få tilgang til et eget domene som også bør være autorisert via API-mekanismen din), men de er ikke utestengt etter noen spesifikasjon. Det som imidlertid bør unngås, er å bruke mer enn en form for autentisering på samme tid.

Når det gjelder PHPs sesjonshåndtering, bør du aldri stole på standard PHP-cookie-tilnærmingen for API-en din, med mindre du vil at PHPSESSIONID-informasjonskapselen skal fungere som API-en sin godkjenningstoken (som jeg ikke anbefaler på noen måte!). Mitt råd vil være å implementere en tilpasset sesjonshåndteringsmekanisme som implementerer din foretrukne autentiseringsmetode.

Ikke avslør interne feil eller implementeringsdetaljer

Gjennom årene har jeg sett dette i utallige anledninger, selv i populære API-er av store selskaper. Det er ikke kult å eksponere interne (for eksempel SQL) feil i svarene dine! Finn en pålitelig måte å logge dem for fremtidig referanse, men oversett dem til en generisk 500 - intern serverfeil i API-svarene dine.

Den obligatoriske xkcd - alltid relevant.

Dette er noe av det første du bør gjøre tidlig i utviklingsprosessen. Sikkerhet bør være en viktig bekymring for en tjeneste som blir utsatt på nettet.

Dette var den første i en serie med tre innlegg på REST API-er.

Du kan lese den neste her:
Del 2: Skjemaforslag, vanlige feil og avskrivninger