Kokosimme teille kaikille Netvisorin rajapintaa vasten sovelluksia toteuttaville listan tärkeimmistä toimintatavoista ja käytännöistä. 

Tietoturva

1. Tuotantopalvelimella on käytettävä salattuja yhteyksiä. 

2. API-avaimien tallentamiseen salattuna sekä niiden oikeaan yksilöivään käyttöön on kiinnitettävä huomiota. Kumppanikohtaiset avaimet ja niillä tehtävät toimenpiteet ovat aina kumppanin vastuulla. Ks. lisätietoa.
   

3. Käsittele rajapinnan kautta saatavaa aineistoa huolellisesti ja lain edellyttämällä tavalla.

   • Huolehdi arkaluontoisen datan poistamisesta suunnitelmallisesti, vrt. GDPR.

   • Älä siirrä tai tallenna turhaan arkaluontoista dataa. Huomioi myös lokitus.

4. Edellytämme, että kumppaneilla on käytössä varautumis- ja toipumiskäytännöt ulkoisia uhkia, hyökkäyksiä, haavoittuvuuksia, teknisiä ongelmia jne. vastaan.

Lisäksi edellytämme, että informoitte meitä välittömästi asiakkaisiimme kohdistuvista mahdollisista uhkista, toteutuneista hyökkäyksistä, tietojen tai kumppanikohtaisten avaimien päätymisestä ulkopuolisten haltuun sekä käynnistätte viipymättä korjaavat toimenpiteet. Olethan välittömästi yhteydessä kumppanitukeemme (kumppanituki.netvisor@visma.com).

Kutsut API:in

1. API toimii varmimmin, kun lähetät kunkin asiakkaan ympäristöön yhden kutsun kerrallaan ja odotat vastausta ennen seuraavan kutsun lähetystä. Päällekkäiset kutsut samaan asiakasympäristöön aiheuttavat erilaisia virhetilanteita asiakkaiden ympäristössä. 
2. Kutsujen aikakatkaisuksi suosittelemme vähintään 360 000 ms. Näin vältät turhat virhetilanteet.
3. Tee isot haut ja tietojen siirrot virka-ajan ulkopuolella, jollei niiden siirtoon virka-aikana ole erityistä tarvetta.
4. Hae/tuo vain tarpeellista dataa.  
   • Vältä ylimääräisen tiedon välitystä tai tallennusta järjestelmien välillä - otathan huomioon GDPR:n. 
   • Tietojen siirron aiheellinen tiheys eroaa resurssi- ja käyttötapauskohtaisesti. Monissa tapauksissa siirto kerran vuorokaudessa tai kuukaudessa riittää.
   • Voit nopeuttaa siirtoja myös sopivilla rajauksilla API-hauissa. 

Integraation valvonta ja virheiden käsittely

1. Lokita ja seuraa rajapinnan liikennettä, mukaan lukien virheet. Integraation tekemät pyynnöt tulee tallentaa lokiin transaktiokohtaisesti.
2. Jos API ei syystä tai toisesta vastaa, voit kokeilla yhteyttä muutaman kerran ja sen jälkeen pitää pidemmän tauon.
3. Tarjoa asiakkaalle näkymä integraation tilasta ja sen siirtohistoriasta.
4. Integraation virheiden hallinnan tulee tapahtua ulkoisessa järjestelmässä. Loppuasiakasta helpottaa, kun integraatio välittää rajapinnan palauttaman virhekuvauksen.

Toteutuksen testaus

1. Tuotantoympäristö ei ole testaamista varten.
2. Testaa kaikki toteutukset ja muutokset testiympäristössä ennen tuotantoon siirtämistä.
3. Älä käytä testiympäristössä oikeaa ja sensitiivistä dataa.
4. Testausvaiheessa on syytä kiinnittää huomiota erityisesti suorituskyvyn hallinnointiin ja tietoturvaan. Ks. lisätietoa.

Muutokset Netvisor API:in ja taaksepäinyhteensopivuus

1. Sanomiin voidaan lisätä uusia kenttiä ilman ennakkovaroitusta. Siksi rajapintaa käyttävät toteutukset tulee ylläpidon helpottamiseksi rakentaa siten, että mahdolliset uudet kentät eivät riko toteutusta.
2. Muutokset rajapintaan pyritään tekemään rikkomatta taaksepäinyhteensopivuutta. Se tarkoittaa, että nykyisiä kenttiä ei muuteta tai poisteta. Jos tällaiselle muutokselle on pakottava tarve, pyritään siitä tiedottamaan hyvissä ajoin etukäteen.
3. Muutoksista rajapintaan tiedotetaan Developer Communityssä.