Sådan fungerer REST-API'er — én forespørgsel frem og tilbage

Sådan fungerer REST-API'er — én forespørgsel frem og tilbage

The interactive FlowJam canvas for this explanation — every lane, row and arrow above is a real QueryChart diagram you can open and edit.

How to read this visual

• Læs de tre kolonner fra venstre mod højre: »Forespørgsel«, »Serverens behandling«, »Svar«.
• Klientrækken og serverrækken skifter, så hver pil er enten klienten, der sender noget, eller serveren, der afgør noget.
• Beslutningen »Er forespørgslen gyldig?« fører enten videre ad happy path eller til afvisningsslutpunktet — de to udfald, ethvert API-kald kan have.

Forespørgslen

»Klienten bygger en HTTP-forespørgsel (metode, URL, headere, body)« er starten på enhver REST-udveksling. Metoden er verbet — GET læser, POST opretter, PUT erstatter, PATCH opdaterer, DELETE fjerner — og URL'en navngiver ressourcen, så »/users/42« er forespørgslen efter én bruger. »Klienten sender forespørgslen over HTTPS« er transporten: REST kører oven på HTTP, og HTTPS holder samtalen privat over den samme internetinfrastruktur, som de andre forklaringer tegner.

Serverens arbejde

»Serveren router URL'en til den rette handler« knytter forespørgslen til kode, og »Er forespørgslen gyldig?« er porten: autentificering (hvem du er), autorisation (om du må) og validering af payloaden sker alle sammen her, og det, der falder igennem, sendes til afvisningsslutpunktet »Serveren returnerer 400 / 401 / 403«. »Handleren kører forretningslogikken« og »Serveren læser eller skriver ressourcen i databasen« er det egentlige arbejde — den del, klienten aldrig ser.

Svaret

»Serveren bygger svaret med en statuskode og en JSON-body« er kontrakten i maskinform: 200 for succes, 201 for oprettet, 404 for ikke fundet, 500 for en serverfejl. »Klienten modtager svaret og parser det« og »Klienten viser resultatet for brugeren« lukker cirklen — turen slutter, hvor den begyndte, i klienten, og netop derfor vender forklaringen tilbage til klientrækken.

Key relationships and takeaways

• REST er en kontrakt i HTTP: metoder er verber, URL'er er ressourcer, og statuskoder er det maskinlæsbare udfald.
• Klienten er tilstandsløs — hver forespørgsel bærer alt, hvad serveren har brug for, så der kræves ingen delt session.
• Valideringen er sikkerhedsgrænsen; en ugyldig forespørgsel afvises, før nogen forretningslogik kører.
• Svaret defineres først af sin statuskode og dernæst af sin body.
• REST-trafik kører på den samme DNS, HTTPS og internetinfrastruktur, som de andre teknologiforklaringer tegner.

When to use this visual

• At undervise udviklere i modellen med HTTP-metode, URL og statuskode, før de designer deres første endpoint.
• At gennemgå et API's kontrakt op mod REST-konventionen — er fejl statuskoder eller 200 med et flag?
• At forankre en samtale om idempotens og caching i, hvordan forespørgsler faktisk bygges og valideres.

Sådan fungerer det

1. Læg jeres egne endpoints ind på forespørgselsboksen

   Tilføj noter med jeres rigtige metoder og ruter — GET /orders, POST /payments — så diagrammet dokumenterer jeres API's overflade.

2. Skriv jeres statuskoder på

   Notér på svartrinnet de koder, jeres API faktisk returnerer for hvert udfald, og tilføj dem, jeres kontrakt bruger ud over 200 og 400.

3. Tilføj autentificering

   Indsæt token-trinnet mellem klienten og valideringsporten — et JWT eller et OAuth-token i Authorization-headeren — så det fremgår, hvor identiteten kommer ind i forespørgslen.

4. Tegn grenene for genforsøg og fejl

   Tilføj eksplicitte slutpunkter for netværksfejl, rate limiting og serverfejl, hver med den klientadfærd (genforsøg, backoff, fejltilstand), den udløser.

Ofte stillede spørgsmål

Hvad er et REST-API?

Et REST-API er et sæt HTTP-endpoints, der eksponerer et systems ressourcer. Klienter handler på ressourcerne med HTTP-metoder — GET for at læse, POST for at oprette, PUT eller PATCH for at opdatere, DELETE for at fjerne — og serveren svarer med en statuskode og en repræsentation, typisk JSON. REST er en stil snarere end en standard, og værdien er, at enhver klient, der taler HTTP, kan bruge det.

Hvad er forskellen på GET, POST, PUT og DELETE?

De er verberne i REST-kontrakten. GET læser en ressource og bør ikke have sideeffekter. POST opretter en ny ressource og returnerer dens identitet. PUT erstatter en ressource i sin helhed og er idempotent — at gentage den ændrer ikke mere. PATCH laver en delvis opdatering. DELETE fjerner en ressource. Tilsammen navngiver verbet og URL'en hele handlingen, og derfor fremhæver forespørgselsboksen i forklaringen metoden først.

Hvorfor er statuskoder vigtige i REST?

Fordi de er forespørgslens maskinlæsbare udfald. En klient kan forgrene på statuskoden uden at parse bodyen: 2xx er succes, 4xx er klientens fejl, 5xx er serverens. API'er, der returnerer 200 med et fejlflag i bodyen, bryder den kontrakt og tvinger hver eneste klient til at behandle svaret som et særtilfælde.

Hvad gør et API »RESTful«?

Den praktiske tjekliste: ressourcer navngivet med URL'er, handlinger udtrykt som HTTP-metoder, tilstandsløse forespørgsler (hver enkelt bærer alt, hvad serveren har brug for), svar, der bruger statuskoder rigtigt, og ofte hypermedia eller versionerede URL'er. Lærredet modellerer turen frem og tilbage — forespørgsel, validering, behandling, svar — som er den form, enhver RESTful udveksling har til fælles.

Redigér dette diagram i QueryChart (FlowJam)

Åbn præcis det REST-lærred, du ser ovenfor, som dit eget diagram, omdøb klient og server til jeres egne tjenester, og notér jeres endpoints.

Redigér dette diagram i QueryChart (FlowJam)