12.7 Ohjelmointirajapinnat (API)

Kaikki uudet web-ohjelmointirajapinnat tulisi toteuttaa käyttäen JSON-formaattia. Tätä puoltavat yksinkertainen esitystapa ja laaja ohjelmistotuki. Yleisesti käytetyissä JSONP- ja XML-formaateissa on molemmissa ongelmansa.

• JSONP-muotoisia rajapintoja ei tulisi käyttää, koska tällöin suoritetaan rajapinnan tarjoamaa dataa suoraan ohjelmakoodina. Tällöin erotus rajapinnan ja rajapintaa käyttävän palvelun välillä puuttuu täysin. Rajapinnan tulisi tarjota ainoastaan dataa, jota palvelu käsittelee.
• XML-jäsentimien (parser) on useasti osoitettu toimivan virheellisesti mahdollistaen datan tulkitsemisen usealla eri tavalla. Tämä muodostuu ongelmaksi, jos dataa tulkitaan useassa eri vaiheessa käyttäen eri jäsentimiä, jolloin dataa saatetaan tulkita useammalla eri tavalla. XML mahdollistaa myös tietosisällön esittämisen usealla eri esitystavalla, jonka jäsennin kuitenkin tulkitsee samalla tavalla.

API-turvallisuus yleisesti

Ohjelmistorajapintojen tulisi varmistua jokaisesta sisään tulevasta kutsusta alla mainituista asioista. Arkkitehtuurista riippuen API-toteutus saattaa luottaa välissä olevaan API-välityspalvelimeen tai tehdä nämä tarkistukset itse.

Mikäli jokin tarkistus ei mene läpi, kutsu kannattaa suoraan hylätä ilman, että rajapinnan toteuttava osapuoli lähtisi arvailemaan, mitä kutsuja on tarkoittanut. Mikäli todennus-, valtuutus- tai eheystarkistukset epäonnistuvat, kutsun sisältöä ei pitäisi lähteä lainkaan jäsentämään pidemmälle vaan prosessointi tulisi päättää mahdollisimman tehokkaasti.

• Istuntotunniste: onko istunto voimassa? Mikä on istunnon valtuutuksen taso? (Ks. tämän ohjeen istuntotunnisteisiin liittyvä erityisohje.)
• Pyynnön valtuutus. Varmistutaan siitä, että kutsujalla on oikeus tehdä kysely tähän rajapintaan (esim. API-avain tai istunnon perusteella tehty valtuutus).
• Jos käytetään pyyntötunnisteita (Request ID, ks. yllä), onko kutsussa mukana pyyntötunniste? Jos on, ja teemme itse kutsuja eteenpäin muihin taustapalveluihin, liitämme pyyntötunnisteen näihin kutsuihin. Jos ei ole, generoimme pyyntötunnisteen itse (tai jos sen puuttuminen on epäilyttävää, jätämme pyynnön käsittelemättä).
• Kutsun ja tietojen eheys. Varmistutaan siitä, että kutsu on eheä. Jos käytetään API-avainta tai muuta kutsujan ja rajapinnan välistä salaisuutta, eheystarkistus voidaan sitoa siihen. Tyypillisiä toteutuksia ovat valtuutusten siirtoon JSON Web Tokens (JWT) ja kokonaisten rajapintakutsujen eheystarkistuksiin AWS Signature v4.
• Onko sisään tuleva kutsu oikein muotoiltu? Myös JSON-pohjaisten rajapintojen tapauksessa kutsu tulisi tarkistaa skeemaa vasten, jotta rajapintaan ei esimerkiksi pysty syöttämään ylimääräisiä tietokenttiä. Ellei skeematarkistusta tehdä, nämä ylimääräiset kentät päätyvät erityisesti NoSQL-tapauksissa usein tietokantaan asti ja joka tapauksessa ne indikoivat mahdollista hyökkäysyritystä. Muotoilun tarkastuksessa Domain Driven Design (DDD) saattaa olla hyödyllinen lähestymistapa, ks. Secure by Design
• Valtuutus saada vastauksen tiedot. Joissakin tapauksissa rajapinnan kutsumisen valtuutus ja tietojen saanti rajapinnasta ovat erillisiä valtuutuspäätöksiä.
• Onko kutsu tarpeen lokittaa? (Ks. tämän ohjeen kappale auditointilokituksesta.)
• Asetetaanko vastauksessa kaikki tarpeelliset HTTP-otsakkeet, kuten HSTS ja Content-Type? (Ks. tämän ohjeen kappale HTTP-otsakkeista.)

Mikäli valtuutuksien siirtoon käytetään JWT:tä, sen käyttämien kryptografisten algoritmien ja avainpituuksien valintaan sovelletaan aiempaa TLS 1.2:n ohjetta soveltuvin osin.