5 trinn for å lage en vellykket api

Det er arten av programvareutvikling. Utviklere lager programvare med sluttbruker i tankene. Det virker ganske enkelt, men noen ganger er disse brukerne også medutviklere. De trenger ikke ting fordelt for dem. De trenger ikke engang trenger enkelheten. Alt de ønsker er tilgang - en måte å integrere programvaren din med deres. Det er her et API (applikasjonsprogrammeringsgrensesnitt) kommer inn. Jeg håper å fremheve fem trinn som du kan ta for å lage et vellykket API.

Gjør leksene dine

Når det gjelder programvareutvikling, er det ingen av oss som ønsker å oppfinne rattet på nytt. På dette tidspunktet har nesten alle store webselskaper API-er for programvareproduktene sine. Studer disse APIene og prøv å finne ut av de forskjellige designbeslutningene som gikk ut på å lage dem.

Det er mange forskjellige teknologier der ute, men de fleste av APIene du vil se kommer til å bruke enten et RESTful grensesnitt, eller SOAP. Hvis du er på gjerdet om hvilket API-grensesnitt du skal bruke, vil jeg foreslå at du bruker en RESTful tilnærming ved å bruke HTTP-protokollen. Det er enklere enn SOAP, det er for tiden mer populært, og det vil være lettere å komme i gang når du bruker et nettbasert programvareprodukt.

Være konsekvent

En av tingene som utviklerne setter mest pris på er konsistens. Dette inkluderer blant annet adresserbarhet, inndatargumenter, utdataformater og feilhåndtering.

Når du bruker en RESTful tilnærming, er det mange forskjellige URI-navneplaner. Hver og en har sine støttespillere, så bare velg en og hold deg til den. Det samme gjelder inngangs- og utgangsstruktur. De fleste API-er støtter bruk av XML og JSON som input- og output-formater. Jeg vil foreslå å støtte begge, men velge et standardformat.

For innspill, skal inngangskravene dine navngis konsekvent og være fornuftige i sammenheng med API-samtalen du foretar. For utdata, sørg for at du bruker vanlige datastrukturoppsett. Hvis du pakker inn output fra ett API-anrop i en XML-tag, kan du vurdere å gjøre det med de andre samtalene dine.

Det er en vanlig praksis å inkludere en slags statusflagg i outputdataene du sender tilbake til klienten. Når du bruker en RESTful API-tilnærming, bør dette gjøres ved hjelp av HTTP-statuskoder. Hvis du for eksempel nettopp behandlet en PUT-forespørsel på et eksisterende dataobjekt, vil HTTP-statuskoden du inkluderer i svaret, variere avhengig av utfallet av forespørselen.

I stedet for et vilkårlig flagg som indikerer samtalenes status, kan en standard "200 OK" -statuskode brukes til å indikere at forespørselen var vellykket, mens en "400 dårlig forespørsel" -statuskode kunne brukes til å indikere at forespørselen var misformet. Det er ganske mange HTTP-statuskoder som kan brukes i forskjellige situasjoner.

Bruk OAuth

De fleste programvareprodukter vil involvere en slags brukerautentisering for å få tilgang til beskyttede ressurser for den brukeren. Når det gjelder API-er, er det en dårlig praksis å ha klienten til å samle inn brukeropplysningene for å sende til serveren din. Det er her OAuth kommer inn.

OAuth gir mange fordeler i forhold til tredjeparts autentisering av brukernavn / passord. Fremfor alt har klienten aldri tilgang til brukerens legitimasjon. Brukeren blir omdirigert til serveren din når han eller hun logger seg på. Etter at brukeren har logget seg inn på nettstedet ditt, blir han eller hun omdirigert tilbake til klienten der klienten vil få et tilgangstoken som kan brukes i fremtidige forespørsler om beskyttede ressurser.

En annen viktig fordel med å bruke OAuth er brukerens mulighet til å avbryte klienttilgang når som helst. Hvis brukeren bestemmer at de av en eller annen grunn ikke lenger ønsker at klienten skal kunne få tilgang til beskyttede ressurser på sine vegne, går de ganske enkelt til et grensesnitt du har opprettet og kansellerer tilgangen til klienten.

Start tidlig

Noe av det viktigste du kan gjøre for å gjøre API-en din til en suksess, er å starte tidlig. Når du skriver denne funksjonen for å opprette en oppføring i databasen din, kan du ta den ekstra tiden og skrive et API-grensesnitt for det.

Skriv god dokumentasjon

Ingenting dreper et API raskere enn å ikke ha god dokumentasjon. Mens noen utviklere kan ta et dårlig dokumentert API og finne ut hvordan det skal fungere, vil de fleste ikke.

Du bør dokumentere hvert API-anrop som du har tilgjengelig og kategorisere API-anropene dine etter den datatypen de utfører. Sammen med å dokumentere endepunktene for API-anropene selv, bør du systematisk definere de nødvendige og valgfrie inndatargumenter, så vel som utdatastrukturer. Inngangsargumenter bør føre en standardverdi hvis det er en, og også indikere det forventede dataformatet som et nummer eller en streng. Til slutt bør hvert API-anrop ha en liste over feilforhold og statuskoder.

For å avrunde dokumentasjonen, må du huske å inkludere ett eller to eksempler for vanlige input- og output-scenarier for hvert API-anrop.

API-utvikling: Keep It Simple

Selv om det kan se ut som å utvikle en API er en komplisert bestrebelse, er ikke ideen om et API i seg selv et nytt konsept, og det er en stor mengde tilgjengelig dokumentasjon om hvert tema vi berørte her. Bare sørg for å bruke god praksis der du kan finne dem, og gi et konsistent, godt dokumentert grensesnitt.