RESTful API-design - Trin for trin guide

Den (lidt) definitive guide til opbygning af bedre API'er

Foto af Marius Masalar på Unsplash

Som softwareudviklere bruger eller bygger de fleste af os REST API'er i det daglige liv. API'er er standardformatet for kommunikation mellem systemerne. Amazon er det bedste eksempel på, hvordan API'er kan bruges effektivt til kommunikation.

I denne artikel vil jeg tale om, hvordan du designe dine RESTful API'er bedre for at undgå almindelige fejl.

Jeff Bezos '(nøgle til succes) mandat

Nogle af jer har måske allerede været opmærksomme på Jeff Bezos 'mandat til udviklerne i Amazon. Hvis du aldrig fik en chance for at høre om det, er følgende punkter kernen i det.

  1. Alle hold vil fremover afsløre deres data og funktionalitet gennem service-grænseflader.
  2. Hold skal kommunikere med hinanden gennem disse grænseflader.
  3. Der vil ikke være nogen anden form for interprocesskommunikation tilladt - ingen direkte linking, ingen direkte læsning af et andet teams datalager, ingen model med delt hukommelse, ingen bagdøre overhovedet. Den eneste tilladte kommunikation er via serviceinterfaceopkald via netværket.
  4. Det betyder ikke noget, hvilken teknologi de bruger. HTTP, Corba, pubsub, brugerdefinerede protokoller - betyder ikke noget. Bezos er ligeglad.
  5. Alle servicegrænseflader skal uden undtagelse være designet fra bunden til at være eksternaliserbare. Det vil sige, at teamet skal planlægge og designe for at kunne udsætte grænsefladen for udviklere i omverdenen. Ingen undtagelser.
  6. Enhver, der ikke gør dette, bliver fyret.

Til sidst viste det sig at være nøglen til Amazons succes. Amazon kunne bygge skalerbare systemer og senere kunne også tilbyde dem som tjenester som Amazon Web Services.

Principper for design af RESTful API'er

Lad os nu forstå de principper, vi skal følge, mens vi designer de RESTful API'er.

Hold det simpelt

Vi er nødt til at sørge for, at API-basens URL er enkel. Hvis vi for eksempel ønsker at designe API'er til produkter, skal det designes som:

/Produkter
/ produkter / 12345

Den første API er at få alle produkter, og den anden er at få et specifikt produkt.

Brug substantiv og ikke verbene

En masse udviklere laver denne fejl. De glemmer generelt, at vi har HTTP-metoder til os til at beskrive API’erne bedre og ender med at bruge verb i API-URL’erne. F.eks. Skal API til at hente alle produkter være:

/Produkter

og ikke som vist nedenfor

/ getAllProducts

Nogle almindelige URL-mønstre har jeg set indtil videre.

Brug af de rigtige HTTP-metoder

RESTful API'er har forskellige metoder til at indikere den type operation, vi skal udføre med denne API.

  • FÅ - For at få en ressource eller samling af ressourcer.
  • POST - For at oprette en ressource eller samling af ressourcer.
  • PUT / PATCH - At opdatere den eksisterende ressource eller samling af ressourcer.
  • SLET - For at slette den eksisterende ressource eller indsamlingen af ​​ressourcer.

Vi er nødt til at sikre, at vi bruger den rigtige HTTP-metode til en given operation.

Brug flertals

Dette emne kan lidt diskuteres. Nogle mennesker kan lide at bevare URL-adressen til ressourcen med flertalsnavne, mens andre kan lide at holde den entydig. For eksempel -

/Produkter
/produkt

Jeg kan godt lide at holde det flertal, da det undgår forvirring om, hvorvidt vi taler om at få en enkelt ressource eller en samling. Det undgår også at tilføje yderligere ting som at vedhæfte alt til basis-URL'en, f.eks. / Produkt / alle

Nogle mennesker kan måske ikke lide dette, men mit eneste forslag er at holde det ensartet i hele projektet.

Brug parametre

Nogle gange er vi nødt til at have en API, der skal fortælle mere historie end bare ved id. Her skal vi gøre brug af forespørgselsparametre til at designe API'en.

  • / produkter? navn = 'ABC' bør foretrækkes frem for / getProductsByName
  • / produkter? type = 'xyz' bør foretrækkes frem for / getProductsByType

På denne måde kan du undgå lange webadresser med enkel design.

Brug korrekte HTTP-koder

Vi har masser af HTTP-koder. De fleste af os ender kun med to - 200 og 500! Dette er bestemt ikke god praksis. Følgende er nogle ofte anvendte HTTP-koder.

  • 200 OK - Dette er mest almindeligt anvendte HTTP-kode for at vise, at den udførte handling er vellykket.
  • 201 CREATED - Dette kan bruges, når du bruger POST-metoden til at oprette en ny ressource.
  • 202 ACCEPTED - Dette kan bruges til at anerkende anmodningen sendt til serveren.
  • 400 DÅRLIG FORESPØRGSEL - Dette kan bruges, når validering af klientsiden input mislykkes.
  • 401 UNAUTHORIZED / 403 FORBIDDEN— Dette kan bruges, hvis brugeren eller systemet ikke er autoriseret til at udføre en bestemt handling.
  • 404 NOT FOUND - Dette kan bruges, hvis du leder efter en bestemt ressource, og den ikke er tilgængelig i systemet.
  • 500 INTERN SERVER FEJL - Dette skal aldrig kastes eksplicit, men kan forekomme, hvis systemet mislykkes.
  • 502 DÅRLIG GATEWAY - Dette kan bruges, hvis serveren modtog et ugyldigt svar fra opstrømsserveren.

Versionering

Versionering af API'er er meget vigtig. Mange forskellige virksomheder bruger versioner på forskellige måder. Nogle bruger versioner som datoer, mens andre bruger versioner som forespørgselsparametre. Jeg vil generelt gerne holde det præfixeret til ressourcen. For eksempel:

/ V1 / produkter
/ V2 / produkter

Jeg vil også undgå at bruge /v1.2/produkter, da det indebærer, at API ofte ændrer sig. Prikker (.) Er muligvis ikke let synlige i URL'erne. Så hold det enkelt.

Det er altid god praksis at holde bagudkompatibilitet, så hvis du ændrer API-versionen, får forbrugerne tid nok til at gå til den næste version.

Brug pagination

Brug af pagination er et must, når du udsætter en API, som muligvis returnerer enorme data, og hvis der ikke foretages korrekt belastningsbalancering, kan forbrugeren muligvis ende med at nedbringe tjenesten. Vi er altid nødt til at huske, at API-designen skal være fuldt bevis og idiotsikker.

Brug af grænse og forskydning anbefales her. For eksempel / produkter? Limit = 25 & offset = 50. Det tilrådes også at holde en standardgrænse og en standardforskydning.

Understøttede formater

Det er også vigtigt at vælge, hvordan din API reagerer. De fleste af de moderne applikationer skal returnere JSON-svar, medmindre du har en ældre app, som stadig har brug for at få et XML-svar.

Brug korrekte fejlmeddelelser

Det er altid god praksis at opbevare et sæt fejlmeddelelser, som applikationen sender og svare på det med korrekt id. Hvis du f.eks. Bruger Facebook-grafiske API'er, i tilfælde af fejl, returnerer det en meddelelse som denne:

{
  "fejl": {
    "meddelelse": "(# 803) Nogle af de aliaser, du anmodede om, findes ikke: produkter",
    "type": "OAuthException",
    "kode": 803,
    "fbtrace_id": "FOXX2AhLh80"
  }
}

Jeg har også set nogle eksempler, hvor folk returnerer en URL med en fejlmeddelelse, der fortæller dig mere om fejlmeddelelsen, og hvordan du også håndterer den.

Brug af OpenAPI-specifikationer

For at holde alle teams i din virksomhed overholdt visse principper, kan brug af OpenAPI-specifikationer være nyttig. OpenAPI giver dig mulighed for først at designe dine API'er og dele det med forbrugerne på en lettere måde.

Konklusion

Det er helt tydeligt, at hvis du vil kommunikere bedre, er API'er vejen at gå. Men hvis de er designet dårligt, kan det øge forvirringen. Så læg din bedste indsats i at designe godt, og resten er bare implementeringen.

Tak fordi du læste

Hvis du stødte på nogle bedre måder at designe API'er, er du velkommen til at dele dem i kommentarfeltet. Alle feedback er velkomne!