Repository navigation
Terminaalin API v3
Vikakoodit, joita käytetään vastauksen error-code-parametrissa, muodostetaan seuraavasti.
-
Eri osia erottaa tavuviiva (-).
-
Mitä kauempana osa on koodin alkua, sitä yksityiskohtaisempi tieto se on (esim.
2-email-syntax), -
Koodin ensimmäinen osa kertoo vian luonteen:
0, kun pyynnön URL on viallinen.
1, kun jokin pakollinen tieto puuttuu.
2, kun jokin annettu tieto ei ole kelvollinen. -
Mahdollinen toinen osa kertoo, minkä niminen tieto puuttuu tai on epäkelpo.
-
Vikakoodit ovat kokonaisuudessaan muotoa
vian_numero-kentän_nimi-lisä-tietoja-...
Kirjautumiskomennot hoitavat sisään- ja uloskirjautumiset sekä kirjautuneisuuden testaamisen.
POST /login HTTP/1.1username string - Käyttäjätunnus. Pakollinen.
password string - Salasana. Pakollinen.
- Mikäli kirjautuminen onnistui, tulos on:
HTTP/1.1 200 OK{
"logged-in": true
}- Mikäli kirjautuminen epäonnistui:
HTTP/1.1 400 Bad Request{
"logged-in": boolean,
"error-code": [string, ...]
}true, mikäli samassa istunnossa oltiin kirjautuneena jo aiemmin.
false, mikäli samassa istunnossa ei oltu kirjautuneena jo aiemmin.
1-username, mikäli käyttäjätunnus puuttuu.
1-password, mikäli salasana puuttuu.
2, mikäli tunnusta ei ole olemassa tai salasana ei täsmää.
POST /login/out HTTP/1.1- Uloskirjautumisen tulos on:
HTTP/1.1 200 OK{
"logged-in": false
}GET /login/test HTTP/1.1- Kirjautuneisuuden testaamisen tulos on:
HTTP/1.1 200 OK{
"logged-in": boolean
}true, mikäli samassa istunnossa oltiin kirjautuneena.
false, mikäli samassa istunnossa ei oltu kirjautuneena.
Tilinhallintakomennot hoitavat tilin luonnin ja poiston sekä tilin tietojen haun ja päivittämisen.
PUT /account/create HTTP/1.1username string - Käyttäjän käyttäjätunnus. Pakollinen.
password string - Käyttäjän salasana. Pakollinen.
email string - Käyttäjän sähköpostiosoite. Oletuksena vapaaehtoinen, mutta konfiguroitavissa pakolliseksi.
name string - Käyttäjän oikea nimi. Oletuksena vapaaehtoinen, mutta konfiguroitavissa pakolliseksi.
company string - Yrityksen nimi. Oletuksena vapaaehtoinen, mutta konfiguroitavissa pakolliseksi.
department string - Yrityksen osaston nimi. Oletuksena vapaaehtoinen, mutta konfiguroitavissa pakolliseksi.
test boolean - Arvon ollessa true, tiliä ei luoda vaan ainoastaan syötteet validoidaan.
- Mikäli
Test-parametrin arvo oli true ja tilin luominen onnistuisi:
HTTP/1.1 204 No Content- Mikäli tilin luominen onnistui:
HTTP/1.1 201 Created- Mikäli vähintään yksi annettu tieto ei täyttänyt sille asetettuja ehtoja:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}1-paramtrinimi, mikäli jokin pakollinen tieto puuttuu. Pakollisia ovat vähintään käyttäjätunnus ja salasana. Muut ovat oletuksena vapaaehtoisia, mutta ne voidaan konfiguroida pakollisiksi.
2-username, mikäli käyttäjätunnus on jo varattu.
2-parametrinimi, mikäli jokin muu tieto (salasana, oikean nimi, sähköpostiosoite, yrityksen nimi tai sen osaston nimi) ei täytä sille asetettuja vaatimuksia.
DELETE /account/remove HTTP/1.1- Mikäli tilin poistaminen onnistui:
HTTP/1.1 204 No Content- Mikäli käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 ForbiddenGET /account HTTP/1.1field-names lista - Pyydettyjen kenttien nimet pilkulla erotettuna listana. Vaihtoehtoja ovat username, email, verified-email, name, company ja department. Esim.
username,email. Mikäli parametri puuttuu, sen käsitellään sisältävän kaikki kentät.
- Mikäli tietojen haku onnistui:
HTTP/1.1 200 OK{
"username": string,
"email": string,
"verified-email": string,
"name": string,
"company": string,
"department": string
}Vastauksen sisällössä ovat vain ne tiedot, joita pyydettiin ja jotka ovat olemassa.
- Mikäli käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 ForbiddenPATCH /account/update HTTP/1.1email string - Käyttäjän sähköpostiosoite. Vapaaehtoinen.
name string - Käyttäjän oikea nimi. Vapaaehtoinen.
company string - Yrityksen nimi. Vapaaehtoinen.
department string - Yrityksen osaston nimi. Vapaaehtoinen.
test boolean - Arvon ollessa true, tilin tietoja ei päivitetä vaan ainoastaan syötteet validoidaan.
Vain ne tiedot välitetään (yksi tai useampi), jotka päivitetään.
- Mikäli
Test-parametrin arvo oli true ja tietojen päivittäminen onnistuisi:
HTTP/1.1 204 No Content- Mikäli tietojen päivittäminen onnistui:
HTTP/1.1 204 No Content- Mikäli käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 Forbidden- Mikäli vähintään yksi annettu tieto ei täyttänyt sille asetettuja ehtoja:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}0, mikäli osoite ei ollut yllä esitetyn mukainen.
1, yhtään hyväksyttävää päivitettävää tietoa (sähköpostiosoite, oikea nimi, yrityksen nimi tai sen osaston nimi) ei välitetty.
2-parametrinimi, mikäli jokin annettu tieto (sähköpostiosoite, oikea nimi, yrityksen nimi tai sen osaston nimi) ei täytä sille asetettuja vaatimuksia.
POST /account/change-password HTTP/1.1old-password string - Vanha salasana. Pakollinen.
new-password string - Uusi salasana. Pakollinen.
- Mikäli salasanan vaihtaminen onnistui:
HTTP/1.1 200 OK{
"logged-in": false
}- Mikäli käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 Forbidden- Mikäli salasanan vaihtaminen epäonnistui:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}1-oldpassword, mikäli vanha salasana puuttui.
1-newpassword, mikäli uusi salasana puuttui.
2, mikäli vanha salasana ei ollut kirjautuneen käyttäjän salasana tai uusi salasana ei täyttänyt sille asetettuja vaatimuksia.
Koodienkäsittelykomennot hoitavat eri koodien luomisen käyttämisen ja hallinnan.
PUT /code/create-email-code HTTP/1.1- Mikäli koodin luominen onnistui:
HTTP/1.1 201 Created- Mikäli sähköpostin vahvistuskoodia ei voitu luoda:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}3-unverified-email, mikäli käyttäjällä ei ollut vahvistamatonta sähköpostia.
- Mikäli käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 ForbiddenPUT /code/create-password-code HTTP/1.1username string - Käyttäjätunnus. Vapaaehtoinen.
email string - Sähköpostiosoite. Vapaaehtoinen.
- Mikäli koodin luominen onnistui:
HTTP/1.1 201 Created- Mikäli
email-parametri on useamman käyttäjän vahvistettu sähköpostiosoite jausername-parametria ei välitetty:
Huom! Koodia ei luotu vielä.
HTTP/1.1 200 OK{
"users": [string, ...]
}string, käyttäjätunnus, jonka vahvistettu sähköposti vastaa email-parametria.
- Mikäli salasanan palautuskoodia ei voitu luoda:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}1, mikäli käyttäjätunnus ja salasana puuttuvat molemmat.
2-username, mikäli käyttäjää ei ole olemassa.
2-email, mikäli sähköpostiosoite ei ollut yhdenkään käyttäjän vahvistettu sähköposti.
2, mikäli sekä käyttäjätunnus että sähköpostiosoite annettiin, mutta ne eivät vastaa toisiaan.
3-verified-email, mikäli käyttäjällä ei ollut vahvistettua sähköpostia.
- Mikäli käyttäjä oli kirjautuneena:
HTTP/1.1 403 ForbiddenPOST /code/verify-email HTTP/1.1code string - Sähköpostin vahvistuskoodi. Pakollinen.
- Mikäli sähköpostin vahvistaminen onnistui:
HTTP/1.1 204 No Content- Mikäli sähköpostin vahvistaminen epäonnistui:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}1-code, mikäli koodi puuttui.
2-code, mikäli code-parametri ei ollut käyttäjän voimassa oleva sähköpostin vahvistuskoodi.
- Mikäli käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 ForbiddenPOST /code/reset-password HTTP/1.1code string - Sähköpostin vahvistuskoodi. Pakollinen.
new-password string - Vapaaehtoinen.
- Mikäli salasanan palauttaminen onnistui:
HTTP/1.1 204 No Content- Mikäli
new-password-parametri puuttuu:
Huom! Koodia ei käytetty vielä. Mikäli koodi on viallinen, seuraava kohta käsittelee pyynnön.
HTTP/1.1 200 OK{
"username": string,
"email": string
}Tiedot ovat sen käyttäjän käyttäjätunnus ja vahvistettu sähköpostiosoite, jolla on annettu salasanan palautuskoodi.
- Mikäli salasanan palauttaminen epäonnistui:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}1-code, mikäli koodi puuttuu.
2-code, mikäli koodi ei ole yhdenkään käyttäjän voimassa oleva salasanan palautuskoodi.
2-newpassword, mikäli uusi salasana ei täytä sille asetettuja vaatimuksia.
- Mikäli käyttäjä oli kirjautuneena:
HTTP/1.1 403 ForbiddenDELETE /code/remove-email-code HTTP/1.1code stirng - Poistettava sähköpostin vahvistuskoodi. Pakollinen.
- Mikäli koodin poistaminen onnistui tai sitä ei ollut olemassa:
HTTP/1.1 200 OK{
"removed": boolean
}true, mikäli sähköpostin vahvistuskoodi oli olemassa, ja se poistettiin.
false, mikäli sähköpostin vahvistuskoodia ei ollut olemassa.
- Mikäli koodin poistaminen epäonnistui:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}1-code, mikäli koodi puuttui.
2-code, koodi oli epäkelpo (esim. väärän pituinen).
DELETE /code/remove-password-code HTTP/1.1code string - Poistettava salasanan palautuskoodi. Pakollinen
- Mikäli koodin poistaminen onnistui, tai sitä ei ollut olemassa:
HTTP/1.1 200 OK{
"removed": boolean
}true, mikäli oli olemassa käyttäjään sidottu salasanan palautuskoodi, ja se poistettiin.
false, mikäli ei ollut olemassa käyttäjään sidottua salasanan palautuskoodia.
- Mikäli koodin poistaminen epäonnistui:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}1-code, mikäli koodi puuttui.
2-code, koodi oli epäkelpo (esim. väärän pituinen).
- Mikäli käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 ForbiddenNäkyvyysaluekomennot huolehtivat näkyvyysalueiden luomisesta ja poistamisesta sekä tietojen hausta ja päivittämisestä.
PUT /scope/create HTTP/1.1company-name string - Näkyvyysalueen yrityksen nimi. Pakollinen.
department-name string - Näkyvyysalueen yrityksen osaston nimi. Vapaaehtoinen.
test boolean - Arvon ollessa true, näkyvyysaluetta ei luoda vaan ainoastaan syötteet validoidaan.
- Mikäli
Test-parametrin arvo oli true ja näkyvyysalueen luominen onnistuisi:
HTTP/1.1 204 No Content- Mikäli näkyvyysalueen luominen onnistui:
HTTP/1.1 201 Created- Mikäli vähintään yksi annettu tieto ei täyttänyt sille asetettuja ehtoja:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}
1-companyname, mikäli yrityksen nimi puuttui.
2-companyname, mikäli yrityksen nimi ei täyttänyt sille asetettuja vaatimuksia.
2-departmentname, mikäli osaston nimi välitettiin mutta se ei täyttänyt sille asetettuja vaatimuksia.
2, mikäli on jo olemassa näkyvyysalue täysin samoilla tiedoilla.
- Mikäli käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 ForbiddenDELETE /scope/remove HTTP/1.1id int - Poistettavan näkyvyysalueen ID. Pakollinen.
- Mikäli näkyvyysalueen poistaminen onnistui:
HTTP/1.1 204 No Content- Mikäli näkyvyysalueen poistaminen epäonnistui:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}1-id, mikäli ID puuttui.
2-id-syntax, mikäli ID:tä ei voitu tulkita luonnolliseksi luvuksi.
2-id, mikäli ei ollut olemassa näkyvyysaluetta annetulla ID:llä.
- Mikäli käyttäjällä ei ollut näkyvyysalueeseen ylläpito-oikeuksia tai käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 ForbiddenGET /scope HTTP/1.1id int - Pyydetyn näkyvyysalueen ID. field-names lista - Pyydettyjen kenttien nimet pilkulla erotettuna listana. Vaihtoehtoja ovat company-name ja department-name. Mikäli parametri puuttuu, sen käsitellään sisältävän kaikki kentät.
- Mikäli tietojen haku onnistui:
HTTP/1.1 200 OK{
"company-name": string,
"department-name": string
}Vastauksen sisällössä ovat vain ne tiedot, joita pyydettiin ja jotka ovat olemassa.
- Mikäli tietojen haku epäonnistui:
HTTP/1.1 400 Bad Request{
"error-code": [stirng, ...]
}1-id, mikäli ID puuttui.
2-id-syntax, mikäli ID:tä ei voitu tulkita luonnolliseksi luvuksi.
2-id, mikäli ei ollut olemassa näkyvyysaluetta annetulla ID:llä.
- Mikäli käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 ForbiddenPATCH /scope/update HTTP/1.1id int - Muokattavan näkyvyysalueen ID. Pakollinen.
company-name string - Näkyvyysalueen yrityksen nimi. Vapaaehtoinen.
department-name string - Näkyvyysalueen yrityksen osaston nimi. Vapaaehtoinen.
test boolean - Arvon ollessa true, näkyvyysalueen tietoja ei päivitetä vaan ainoastaan syötteet validoidaan.
Vain ne tiedot välitetään (yksi tai useampi), jotka päivitetään.
- Mikäli Test-parametrin arvo oli true ja tietojen päivittäminen onnistuisi:
HTTP/1.1 204 No Content- Mikäli tietojen päivittäminen onnistui:
HTTP/1.1 204 No Content- Mikäli tietojen päivittäminen epäonnistui:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}
1-id, mikäli ID puuttui.
1, mikäli yhtään hvyäksyttävää päivitettävää tietoa (yrityksen nimi tai sen osaston nimi) ei välitetty.
2-id-syntax, mikäli ID:tä ei voitu tulkita luonnolliseksi luvuksi.
2-id, mikäli ei ollut olemassa näkyvyysaluetta annetulla ID:llä.
2-parametrinimi, mikäli jokin annettu tieto (yrityksen nimi tai sen osaston nimi) ei täytä sille asetettuja vaatimuksia.
- Mikäli käyttäjällä ei ollut näkyvyysalueeseen ylläpito-oikeuksia tai käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 ForbiddenPOST /scope/use HTTP/1.1id int - Näkyvyysalueen ID.
- Mikäli käytettävän näkyvyysalueen vaihtaminen onnistui:
HTTP/1.1 200 OK- Mikäli käytettävän näkyvyysalueen vaihtaminen epäonnistui:
HTTP/1.1 400 Bad Request{
"error-code": [string, ...]
}
1-id, mikäli ID puuttui.
2-id-syntax, mikäli ID:tä ei voitu tulkita luonnolliseksi luvuksi.
2-id, mikäli ei ollut olemassa näkyvyysaluetta annetulla ID:llä.
- Mikäli käyttäjällä ei ollut näkyvyysalueeseen mitään oikeuksia tai käyttäjä ei ollut kirjautuneena:
HTTP/1.1 403 Forbidden