5 trin til at oprette en vellykket api

Det er arten af ​​softwareudvikling. Udviklere opretter software med slutbrugeren i tankerne. Det virker temmelig enkelt, men nogle gange er disse brugere også medudviklere. De har ikke brug for ting fordelt for dem. De behøver ikke engang brug for enkelheden. Alt, hvad de ønsker, er adgang - en måde at integrere din software med deres. Det er her en API (applikationsprogrammeringsgrænseflade) kommer ind. Jeg håber at fremhæve fem trin, som du kan tage for at oprette et vellykket API.

Lav dine lektier

Når det kommer til softwareudvikling, ønsker ingen af ​​os at opfinde hjulet igen. På dette tidspunkt har næsten alle store webfirmaer API'er til deres softwareprodukter. Undersøg disse API'er og prøv at samle de forskellige designbeslutninger, der gik ind i at skabe dem.

Der er mange forskellige teknologier derude, men de fleste af de API'er, du vil se, bruger enten en RESTful interface eller SOAP. Hvis du er ved hegnet om, hvilken API-grænseflade du vil bruge, vil jeg foreslå, at du går med en RESTful-tilgang ved hjælp af HTTP-protokollen. Det er enklere end SOAP, det er i øjeblikket mere populært, og det vil være lettere at komme i gang, når du bruger et webbaseret softwareprodukt.

Være konsekvent

En af de ting, som udviklerne sætter mest pris på, er konsistens. Dette inkluderer blandt andet adresserbarhed, input-argumenter, outputformater og fejlhåndtering.

Når du bruger en RESTful-tilgang, er der mange forskellige URI-navneplaner. Hver har sine tilhængere, så bare vælg en og hold dig fast ved den. Det samme gælder input og output struktur. De fleste API'er understøtter brug af XML og JSON som input- og outputformater. Jeg vil foreslå at støtte begge, men vælge et standardformat.

Til input skal dine inputkrav navngives konsekvent og være fornuftige i sammenhæng med det API-opkald, du foretager. For output skal du sikre dig, at du bruger almindelige datastrukturlayouts. Hvis du indpakker output fra et API-opkald i et XML-tag, kan du overveje at gøre det med dine andre opkald.

Det er en almindelig praksis at inkludere en slags statusflag i de outputdata, du sender tilbage til klienten. Når du bruger en RESTful API-tilgang, skal dette gøres ved hjælp af HTTP-statuskoder. Hvis du for eksempel netop har behandlet en PUT-anmodning på et eksisterende dataobjekt, varierer HTTP-statuskoden, du inkluderer i dit svar, afhængigt af resultatet af anmodningen.

I stedet for et vilkårligt flag, der angiver opkaldets status, kan en standardkode "200 OK" bruges til at indikere, at anmodningen var vellykket, mens en "400 dårlig anmodning" -statuskode kunne bruges til at indikere, at anmodningen var misdannet. Der er ganske mange HTTP-statuskoder, der kan bruges i forskellige situationer.

Brug OAuth

De fleste softwareprodukter involverer en slags brugergodkendelse for at få adgang til beskyttede ressourcer for denne bruger. Når det kommer til API'er, er det en dårlig praksis at have klienten til at indsamle brugeroplysningerne til at sende til din server. Det er her OAuth kommer ind.

OAuth giver mange fordele i forhold til tredjeparts autentificering af brugernavn / adgangskode. Frem for alt har klienten aldrig adgang til brugerens legitimationsoplysninger. Brugeren omdirigeres til din server, når han eller hun logger på. Når brugeren er logget ind på dit websted, omdirigeres han eller hun tilbage til klienten, hvor klienten får et adgangstoken til brug i fremtidige anmodninger om beskyttede ressourcer.

En anden vigtig fordel ved at bruge OAuth er brugerens evne til at annullere klientadgang til enhver tid. Hvis brugeren beslutter, at de af en eller anden grund ikke længere ønsker, at klienten skal kunne få adgang til beskyttede ressourcer på deres vegne, går de blot til en grænseflade, du har oprettet, og annullerer klientens adgang.

Start tidligt

En af de vigtigste ting, du kan gøre for at gøre din API til en succes, er at starte tidligt. Når du skriver denne funktion for at oprette en post i din database, skal du gå videre og tage den ekstra tid og skrive en API-grænseflade til den.

Skriv god dokumentation

Intet dræber en API hurtigere end ikke at have god dokumentation. Mens nogle udviklere kan tage et dårligt dokumenteret API og finde ud af, hvordan det skal fungere, vil de fleste ikke have det.

Du skal dokumentere hvert API-opkald, du har tilgængeligt, og kategorisere dine API-opkald efter den type data, de udfører. Sammen med at dokumentere slutpunkterne for selve API-opkaldene, skal du systematisk definere de krævede og valgfrie input-argumenter samt outputdatastrukturer. Inputargumenter skal angive en standardværdi, hvis der er en, og også angive det forventede dataformat såsom et nummer eller streng. Endelig skal hvert API-opkald have en liste over fejlbetingelser og statuskoder.

For at afslutte din dokumentation skal du sørge for at medtage et eller to eksempler på fælles input- og output-scenarier for hvert API-opkald.

API-udvikling: Keep It Simple

Selvom det kan se ud til at udvikle en API er en kompliceret bestræbelse, er ideen om en API i sig selv ikke et nyt koncept, og der er en stor mængde tilgængelig dokumentation om hvert emne, vi berørte her. Bare sørg for at bruge god praksis, hvor du kan finde dem, og at give en konsistent, veldokumenteret grænseflade.