Mognad

När man designar ett nytt API så är en av de viktigaste delarna att ta hänsyn till konsumenternas upplevelse av API:et. Utvecklaren kommer att ha en bättre upplevelse av API:et om det redan följer vedertagna och grundläggande koncept.

Ett API som överensstämmer med de principerna och begränsningar som definierar arkitekturstilen RESTÖppnas i ny flik sägs vara ett RESTful API. För att underlätta för utvecklare och säkerställa att ett API är RESTful finns en modell, Richardson Maturity Model.Öppnas i ny flik Denna modell består av fyra nivåer beroende på användning av URL:er, HTTP metoder och principen HATEOASÖppnas i ny flik (Hypermedia As The Engine Of Application State).

Nivå 0 – På denna nivå använder man endast en resurs och en operation. API:et använder den enda resursen som en tunnel där meddelanden skickas fram och tillbaka mellan klient och server. Resursen och operationen, typiskt POST, saknar semantisk betydelse.
Nivå 1 – Till skillnad från nivå 0 använder API:er på nivå 1 flera resurser men använder fortfarande endast en HTTP-operation som en tunnel. På denna nivå har resurserna en semantisk betydelse men operationen saknar det.
Nivå 2 – På nivå 2 använder man flera resurser och använder olika operationer. HTTP operationerna har nu en så korrekt semantisk betydelse som möjligt, t.ex. betyder GET för att hämta, DELETE för att ta bort osv.
Nivå 3 – Ett API på nivå 3 bygger på nivå 2 men servern ger i svaret på en förfrågan, information om nästa möjliga åtgärder förutom den begärda resursen. Nivå 3 följer alltså principen HATEOAS.

Notera att ett API måste uppfylla nivå 3 för att kallas RESTfulÖppnas i ny flik.

Alla API:er SKALL (MOG.01) designas för att uppnå nivå 2 enligt Richardson Maturity Model. Alla API:er BÖR (MOG.02) samtidigt designas för att uppnå nivå 3 enligt Richardson Maturity Model.

I vissa undantagsfall kan man behöva göra avsteg från den korrekta semantiska betydelsen vid val av HTTP-operation. Exempelvis då man inte vill exponera potentiellt känsliga personuppgifter (personnummer) i header-delen i en GET operation eller då söksträngen i URL:n är väldigt lång (över 2000-tecken). Även om RFC 7231Öppnas i ny flik inte förbjuder att man skickar med information i body-delen i en GET saknar body-delen semantisk betydelse och ignoreras av många ramverk och verktyg och bör därför inte användas. I dessa fall brukar man i stället använda POST operationen. Om man använder POST operationerna där man vanligen använder GET operationer SKALL (MOG.03) det dokumenteras tydligt varför. I denna profil betraktas dock detta som att man fortfarande uppnår nivå 2 då man inte använder HTTP-operationen som en tunnel.