APIvastaus

APIvastaus tarkoittaa sovellusrajapinnan (API) palauttamamaa vastausta asiakkaan tekemälle pyynnölle. Sen tarkoituksena on kertoa, onnistuiko pyyntö ja tarjota mahdollisesti pyydetty data tai virhetilanteen tiedot. APIvastaus muodostuu useimmiten HTTP-vastauksesta, jossa on tilakoodi, otsikot ja runko (body).

Tilakoodi kuvaa pyynnön lopputulosta; yleisesti käytettyjä luokkia ovat 2xx menestys, 4xx asiakasvirhe ja 5xx palvelinvirhe. Otsikot voivat sisältää esimerkiksi Content-Typein, Cache-Controlin sekä pyynnön jäljittämistunnisteen (request-id) virheen jäljittämiseksi. Runko sisältää vastauksen varsinaisen sisällön, kuten dataa tai virheviestin.

Runko on usein JSON-muodossa, mutta XML, YAML tai muut muodot ovat mahdollisia riippuen API:n sopimuksesta. Virhetilanteissa vastaukseen liitetään yleensä virheobjekti, joka sisältää virhekoodin, virheilmoituksen ja lisätiedot kuten syyn sekä mahdolliset korjaavat toimenpiteet. API-sopimukset suosivat johdonmukaisia vastauselementtejä ja attribuutteja.

Hyviä käytäntöjä ovat oikea semanttinen rakenne, virheiden yhdenmukainen käsittely sekä tuki versioningille ja ominaisuuksien, kuten sivutuksen, hallinnalle. Dokumentaatio määrittelee vastauksen muodot, mahdolliset poikkeukset ja esimerkkitapaukset. APIvastaus mahdollistaa sekä ohjelmallisen virheenkäsittelyn että saumattoman integraation muiden järjestelmien kanssa.

Esimerkki: HTTP/1.1 200 OK; Content-Type: application/json; Body: {"id":123,"name":"Widget"}