APIpyyntöjen

API-pyynnöt ovat ohjelmistojen välisiä pyyntöjä, joiden avulla toinen ohjelmisto voi hakea tai muuttaa dataa sekä käyttää palveluiden tarjoamia toimintoja. Usein API-pyynnöt välitetään HTTP- tai HTTPS -protokollan yli. Tavallisimpia pyyntömenetelmiä ovat GET, POST, PUT, PATCH ja DELETE, sekä harvemmin HEAD ja OPTIONS. REST-tyypeissä näitä menetelmiä käytetään erilaisten resurssien hallintaan.

Pyyntö koostuu osoitteesta (URI), mahdollisista kyselyparametreista, otsakkeista ja mahdollisesta rungoksi tarkoitetusta sisällöstä. Otsikoissa käytetään usein tunnistusta, kuten Authorization-tunniste tai API-avain; yleisiä ratkaisuja ovat OAuth 2.0 ja JSON Web Tokens. Sisällön muodoksi valitaan yleisesti JSON, mutta XML tai muut formatsit voivat myös tulla kyseeseen.

Vastaukset sisältävät tilakoodin, sisällön sekä mahdollisesti dataa. Yleisimmät statukset ovat 200 OK, 201 Created sekä 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found ja 429 Too Many Requests; 5xx-tilakoodit kertovat palvelinpuolen virheestä. Hyvin suunnitellut API:t tarjoavat johdonmukaiset virhevastaukset ja mahdollistavat virheenkorjauksen tehokkaasti. Monet rajapinnat tukevat myös paginointia ja rajojen asettamista suurille datamäärille.

Parhaat käytännöt kattavat versionoinnin, hyvän dokumentaation sekä API-sopimuksen vakauden. Tärkeää on myös idempotenssi, turvallisuus (HTTPS, oikeudet, syötteen validointi) sekä riittävä logitus ja virheiden hallinta. Esimerkiksi pyyntö GET https://api.example.com/users?limit=10, otsikoissa Authorization: Bearer <token>, Accept: application/json palauttaa yleensä JSON-muotoisen listan.