Usaldusväärne ja intuitiivne API algab selge reeglid hoone liidesed. Järgime REST parimaid tavasid, et iga arendaja teaks, mida oodata: URL struktuur on loogiline, meetodid on meetme jaoks sobivad ja vigu on lihtne tõlgendada.
See vähendab sisenemise künnist, lihtsustab integratsioone ja võimaldab süsteemil skaalata ilma kaose.
URL- ja HTTP-meetodite konventsioonid
| Meetod | Ametisse nimetamine | Proovide päring |
|---|---|---|
| „GET“ | Ressurssi hankimine | „GET/kasutajad/42“ |
| „POST“ | Uue ressursi loomine | „POST/kasutajad“ |
| „PUTI“ | Ressursi täielik uuendamine | „PUT/users/42“ |
| „PATCH“ | Osaline ressursside uuendamine (Opt) „PATCH/users/42“ | |
| „DELETE“ | Ressurssi kustutamine | „DELETE/users/42“ |
Kasutatakse mitmikmärke („/kasutajad “, „/seadmed“, „/mängud “)
Pesastatud üksusi kirjeldatakse hierarhiana („/users/42/sessions “)
Kõik taotlused toimuvad HTTPS kaudu
Viga käitlemise standardid
| Kood | Väärtus | Näidisteade |
|---|---|---|
| `400` | vigane taotlus | „Puuduv nõutav väli: e-post“ |
| `401` | Ei ole lubatud | „Invaliidne märk või aegunud istung“ |
| `403` | Keelatud juurdepääs | „Juurdepääs ressurssidele keelatud“ |
| `404` | ei leitud | „ID 42 kasutaja ei alust“ |
| `409` | Konfliktid (nt dubleerimine) | „E-post juba kasutusel“ |
| `422` | Valideerimisviga | „Väli“ vanus „peab olema number“ |
| `500` | Siseserveri viga | „Ootamatu erand, kontaktandmed“ |
Veareaktsiooni struktuur:
json
{
„viga“: {
„kood“: 400, „sõnum“: „Puudub nõutav väli: e-post,“ „üksikasjad“: {...}
}
}Arendaja kasu
API loogika kiire mõistmine ilma ebavajaliku dokumentatsioonita
Ühtne lähenemisviis kõigile moodulitele ja üksustele
Lihtne silumine ja logimine tänu standardsetele koodidele ja formaatidele
Ühilduvus OpenAPI/Swaggeriga, Postimees, SDK autogeensus
Lihtsustab tuge, testimist ja CI/CD
Kus eriti oluline
Avatud või partneri API platvormid
Projektid koos mitme arendusmeeskonnaga
Microservices arhitektuur või API-first lähenemine
Süsteemid, millel on palju üksusi ja koostoimeid
Ühtsed konventsioonid muudavad API usaldusväärseks, arusaadavaks ja mugavaks. Järgime parimaid puhketavasid, et iga integratsioon toimuks kiiresti, ilma arusaamatute ja maksimaalse prognoositavusega.