Tavanomaisesti verkkopalvelutoteutuksissa pyyntöön vastataan aina tuloksen mukaisella statuskoodilla. Esimerkiksi olematonta rajapintaresurssia kutsuttaessa palvelun pitäisi palauttaa 404 Not Found. Tästä poiketen Netvisorin rajapinta palauttaa oletuksena aina statuskoodin 200 OK. Tämä saattaa aiheuttaa haasteita kumppaneiden integraation lokituksen seurannassa. Tavoitteenamme on vuoden 2025 loppupuolella asteittain siirtyä palauttamaan aina standardin mukaisia statuskoodeja. Muutos auttaa integraatiokumppaneitamme kehittämään toteutuksiaan niin, että virheelliset pyynnöt ovat selkeämpiä myös lähettävässä päässä. Muutoksen myötä kumppaneillamme on mahdollisuus varmistaa toteutuksen toimivuus, mutta myös kehittää oman ratkaisunsa lokitusta ja informatiivisuutta.

Ennen palvelun laajuista muutosta olemme ottaneet käyttöön uuden pyyntöheaderin X-Netvisor-Authentication-UseHTTPResponseStatusCodes. Suosittelemme kaikille kumppaneillemme lisäämään sen integraatiototeutuksen kaikkiin pyyntöihin jo nyt mikäli rajapintatoteutus sen sallii. Headerin voi aktivoida asettamalla arvon 1 headerille X-Netvisor-Authentication-UseHTTPResponseStatusCodes. Tämä mahdollistaa oikeiden statuskoodien, kuten 400, 401, 403, 500, ja 200, käytön rajapinnan vastauksissa:

200 = OK

400 = Virheellinen data

401 = Autentikointi epäonnistui

403 = Palvelun käyttövirhe

500 = Sisäinen palvelinvirhe

Hyödyntämällä standardin mukaisia statuskoodeja integraatiokumppaninamme voitte varmistaa, että pyyntönne ovat onnistuneita Netvisorin rajapinnassa. Vuoden mittaan kontaktoimme eniten virheitä generoivia kumppaneitamme ja ohjeistamme heille headerin käytön, sekä tarvittaessa aktivoimme sen käyttöön kumppanikohtaisesti.

Statuskoodiparannusten ohella kehitämme palvelumme tietoturvaa poistamalla käytöstä haavoittuvia ja heikkoja algoritmeja. Tällä hetkellä rajapintamme tukee autentikaatiossa MD5 ja SHA256 hashing algoritmeja. Tavoitteemme on asteittain korvata ne HMACSHA256 -algoritmilla, joka tuodaan käyttöön piakkoin. Tiedotamme muutoksesta tarkemmin kevään aikana.

Kumppanin shortlist:

1. Varmista, että integraatiototeutuksenne tukee standardin mukaisia statuskoodeja sekä uutta HMACSHA256 -algoritmia. Mikäli tuki puuttuu, suosittelemme aloittamaan jo nyt toteutuksen kehittämisen.

2. Ota käyttöön X-Netvisor-Authentication-UseHTTPResponseStatusCodes  header ja varmista, että statuskoodit palautuvat oikein.

3. Muodosta toteutukseen prosessi virhekoodien käsittelyyn ja lokitukseen niin, että rajapintaa käytetään mahdollisimman tehokkaasti ja läpinäkyvästi.

4. Varmista, että organisaationne ja tarvittaessa asiakkaanne ovat tietoisia muutoksesta.

HTTP Status Codes in Netvisor's API

Typically, in web service implementations, a request is responded to with a status code that matches the outcome. For example, when calling a non-existent API resource, the service should return a 404 Not Found. Contrary to this, Netvisor's API always returns a status code of 200 OK by default. This may pose challenges in monitoring integration logging for partners. Our goal is to gradually transition to always returning standard status codes by late 2025. This change will help our integration partners develop their implementations so that erroneous requests are clearer on the sending end as well. The change will allow our partners to ensure the functionality of their implementation and to enhance their solution's logging and informativity.

Before the service-wide change, we have introduced a new request header, X-Netvisor-Authentication-UseHTTPResponseStatusCodes. We recommend all our partners add it to all integration requests if the API implementation permits. 

The header can be activated by setting the value 1 for the header X-Netvisor-Authentication-UseHTTPResponseStatusCodes. This enables the use of correct status codes, such as 400, 401, 403, 500, and 200, in the API responses:

200 = OK

400 = Invalid Data

401 = Authentication Failed

403 = Service Usage Error

500 = Internal Server Error

By utilizing standard status codes, as our integration partner, you can ensure that your requests are successful in the Netvisor API. Throughout the year, we will contact partners generating the most errors and instruct them on using the header and, if necessary, activate its use on a partner-specific basis.

In addition to the improvements in status codes, we are enhancing our service's security by disabling vulnerable and weak algorithms. Currently, our API supports MD5 and SHA256 hashing algorithms for authentication. We aim to gradually replace them with the HMACSHA256 algorithm, which will be introduced soon. We will provide more detailed information about the change in the spring.

Partner Checklist:

1. Ensure that your integration implementation supports standard status codes and the new HMACSHA256 algorithm. If support is lacking, we recommend starting development now.

2. Implement the X-Netvisor-Authentication-UseHTTPResponseStatusCodes header and ensure that status codes are returned correctly.

3. Create a process in the implementation for handling and logging error codes to use the API as efficiently and transparently as possible.

4. Ensure that your organization and your customers, if necessary, are aware of the change.