Terminaalin API

Terminaalin API

Terminaalin ainoa kutsukelpoinen skripti on terminal.php. Se vaatii salatun yhteyden tai muuten palautetaan HTTP virhe 503. Kaikki sille välitettävät parametrit lähetetään POST-metodilla. Muilla metodeilla lähetettyjä parametreja ei huomioida.

Ainoa pakollinen parametri on command, jonka arvo on kutsuttavan komennon nimi. Kaikki muut parametrit ovat riippuvaisia kutsuttavasta komennosta. Ylimääräisiä parametreja ei huomioida. Mikäli command-parametria ei välitetty tai se ei kelpaa, palautetaan tilakoodi 404.

Komento palauttaa tuloksen aina JSON-oliona tai -taulukkona.

Virhetilanteessa tulos on yksi tai useampi tilakoodi. Tilakoodit noudattavat mahdollisimman tarkasti HTTP:n tilakoodeja.

Tilakoodit

Tilakoodi	Kuvaus
200	OK. Komento suoritettiin onnistuneesti, mutta se ei palauttanut mitään.
400	Bad request. Komentoa ei suoritettu, koska vähintään yksi ei-globaali parametri ei ollut kelvollinen.
401	Unauthorized. Komentoa ei suoritettu, koska tarvitaan kirjautuminen; käyttäjä ei ole kirjautuneena sisään.
403	Forbidden. Komentoa ei suoritettu, koska kirjautuneen käyttäjän oikeudet eivät riitä.
404	Not found. Komentoa ei suoritettu, koska sitä ei ole.
500	Internal server error. Komennon suorittamisen aikana tapahtui virhe.
501	Not implemented. Lisäosaa ei löytynyt.

## Globaalit parametrit

Tässä ovat kaikki komennosta riippumattomat parametrit. Niiden avulla päätellään suoritettava komento.

command

Command on suoritettavan komennon nimi. Mikäli sellaista ei ole olemassa, palautetaan tilakoodi 404.

plugin

Mikäli lisäosaa tai moduulia ei ole, palautetaan tilakoodi 501. Mikäli löytynyt lisäosa tai moduuli ei määrittele commandissa pyydettyä komentoa, palautetaan tilakoodi 404.

Huom! Plugin-parametri on validointijärjestyksessä ennen commandia.

Komennot

command	plugin	ryhmä
login	log	Kirjautumiskäskyt
logout	log	Kirjautumiskäskyt
test	log	Kirjautumiskäskyt
ui-list	conf	Kokoonpanokäskyt
plugin-list	conf	Kokoonpanokäskyt
locale-list	conf	Kokoonpanokäskyt
create	account	Tilinhallintakäskyt
remove	account	Tilinhallintakäskyt
get-settings	account	Tilinhallintakäskyt
set-settings	account	Tilinhallintakäskyt
test-setting	account	Tilinhallintakäskyt
use-code	account	Tilinhallintakäskyt
license	account	Tilinhallintakäskyt
send	account	Tilinhallintakäskyt
list-companies	account	Tilinhallintakäskyt
list	scope	Näkyvyysaluekäskyt
create	scope	Näkyvyysaluekäskyt
remove	scope	Näkyvyysaluekäskyt
get-settings	scope	Näkyvyysaluekäskyt
set-settings	scope	Näkyvyysaluekäskyt
test-setting	scope	Näkyvyysaluekäskyt
use	scope	Näkyvyysaluekäskyt
edit-privileges	scope	Näkyvyysaluekäskyt
create-privilege-code	scope	Näkyvyysaluekäskyt

Kirjautumiskäskyt

command=login&plugin=log

• username – Kirjautumisessa käytettävä käyttäjätunnus
• password – Kirjautumisessa käytettävä salasana

Mikäli username tai password puuttuvat, palautetaan tilakoodi 400. Mikäli username ja password eivät kelpaa (virheelliset tunnukset), palautetaan tilakoodi 401+400. Mikäli käyttäjä oli jo kirjautuneena samassa istunnossa, vanha kirjautuminen lakkaa, kun uusi kirjautuminen tulee voimaan.

Normaalitilanteessa palautetaan tilakoodi 200.

command=logout&plugin=log

Kirjataan käyttäjä ulos, mikäli käyttäjä oli kirjautuneena, ja palautetaan tilakoodi 200.

command=test&plugin=log

Testataan, onko käyttäjä kirjautunut. Mikäli on, palautetaan tilakoodi 200 muuten 401.

Kokoonpanokäskyt

command=ui-list&plugin=conf

• skip-image – Ei arvoa. Ilmoittaa, että kuvat tulee jättää pois

Palautetaan taulukkona oliot kaikista asennetuista käyttöliittymistä.

Jokaisesta käyttöliittymästä annetaan:

• name – käyttöliittymän nimi
• url-name – käyttöliittymän nimi URL-muodossa
• description – käyttöliittymän kuvaus
• image – käyttöliittymän kuvake data-URL-muodossa.
• media-query – ehtolause, jonka perusteella päätellään käyttöliittymän sopivuus laitteeseen

[
    {
      "name": "Lorem ipsum",
      "url-name": "lorem-ipsum",
      "description": "Lorem ipsum dolor sit amet, consectetuer...",
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAA...",
      "media-query": "all"
    }
]

command=plugin-list&plugin=conf

• ui-name – Käyttöliittymän nimi

Palauttaa luettelon kaikista asennetuista lisäosista. Mikäli käyttäjä ei ollut kirjautunut, palautetaan tilakoodi 401. Mikäli ui-name viittaa käyttöliittymään, jota ei ole olemassa, palautetaan tilakoodi 400.

Normaalitilanteessa palautetaan taulukkona oliot kaikista lisäosista järjestettynä countin mukaan suurin ensin. Mikäli lisäosalla ei ole pyydettyä käyttöliittymää, sen kohdalla taulukossa commands-taulukko jätetään tyhjäksi. Mikäli käytettävää näkyvyysaluetta ei ole asetettu, jokaisen lisäosan kohdalla commands-taulukko jätetään tyhjäksi ja count 0:ksi. Mikäli jokaisen lisäosien countien summa on 0, jokainen share jätetään 0:ksi.

Jokaisesta lisäosasta annetaan:

• name – Lisäosan nimi
• count – Näkyvyysalueen tällä lisäosalla olevien tallenteiden määrä (esim. raaka-aineiden määrä)
• share – Countin osuus kaikkien lisäosien yhteenlasketusta countista
• commands – Lisäosan sallimat toiminnot, jotka pitäisi näyttää lisäosaluettelossa. Commands on taulukko toimintojen nimiä, joista ensimmäisenä on oletustoiminto

[
    {
        "name": "raw-materials",
        "count": 152,
        "share": 0.8260869565,
        "commands": [
            "list",
            "new"
        ]
    },
    {
        "name": "products",
        "count": 32,
        "share": 0.1739130435,
        "commands": [
            "list",
            "new"
        ]
    }
]

command=locale-list&plugin=conf

• ui-name – Käyttöliittymän nimi
• plugin-name – Lisäosan nimi

Palauttaa luettelon kaikista asennetuista lokaleista. Mikäli mahdollinen plugin-name ei vastaa yhtäkään asennettua lisäosaa, palautetaan tilakoodi 501. Mikäli ui-name ei vastaa yhtäkään asennettua käyttöliittymää, palautetaan tilakoodi 400.

Normaalitilanteessa palautetaan taulukko kaikista asennetuista lokaleista. Mikäli plugin-name ei ole asetettuna, palautetaan kaikki globaalit lokalet. Mikäli plugin-name on asetettuna, palautetaan kaikki lisäosan tietylle käyttöliittymälle asennetut lokalet.

Jokaisesta lokalesta annetaan:

• code – Koodi, joka yksilöi lokalen (esim. fi-FI tai en-US)

[
    "fi-FI",
    "en-US",
    "sv-FI"
]

Tilinhallintakäskyt

command=create&plugin=account

• username – Käyttäjätunnus
• password – Salasana
• e-mail – Sähköpostiosoite
• name – Oikea nimi
• company – Yritys
• department – Osasto

Mikäli username tai password puuttuvat palautetaan vikakoodi 400. Mikäli username ja/tai password ovat jo toisella käyttäjällä, palautetaan tilakoodi 400. Mikäli palvelimen konfiguraation mukaan sähköposti on pakollinen ja/tai yksilöllinen, ja email ei täytä näitä ehtoja, palautetaan tilakoodi 400.

Normaalitilanteessa palautetaan tilakoodi 200.

Mikäli Yritykset-taulussa on company-department-yhdistelmää vastaava tietue olemassa, yhdistetään käyttäjä siihen. Jos vastinetta ei löydy, luodaan uusi tietue, johon käyttäjä yhdistetään. Mikäli department on annettu mutta company ei, käyttäjää ei yhdistetä mihinkään yritykseen.

command=remove&plugin=account

Mikäli käyttäjä ei ole kirjautuneena, palautetaan tilakoodi 403.

Normaalitilanteessa palautetaan tilakoodi 200.

Toiminto poistaa käyttäjän ja siivoaa tietokannasta kaikki orvoiksi jäävät tietueet.

command=get-settings&plugin=account

• names – Haettavien asetusten nimet pystyviivalla erotettuna

names=username|password|e-mail|name|company|department

Mikäli käyttäjä ei ole kirjautuneena, palautetaan tilakoodi 403.

Normaalitilanteessa palautetaan oliona pyydetyt tilin asetukset. Mikäli käyttäjältä puuttuu jokin asetus (ts. on null tai asetusta ei ole olemassa), sen kohdalla palautetaan tyhjä merkkijono.

[
    "username": "konsta.kayttaja",
    "password": "qg#V3hGri¤4SoD!5gY/6a.",
    "e-mail": "[email protected]",
    "name": "Konsta Käyttäjä",
    "company": "Esimerkki Oy",
    "department": ""
]

command=set-settings&plugin=account

• names – Asetettavien asetusten nimet pystyviivalla erotettuna
• values – Asetettavien asetusten arvot pystyviivalla erotettuna (jos pystyviiva esiintyy arvossa, se pitää escapettaa takakenoviivalla)

names=password|e-mail|name|company|department
values=|||Offer Calculator \|Fi\| Foundation|Development

Mikäli käyttäjä ei ole kirjautuneena, palautetaan tilakoodi 403. Mikäli yksikin name ei ole olemassa, palautetaan tilakoodi 400. Mikäli names- values listojen koot eivät ole samat, palautetaan tilakoodi 400. Mikäli yksikin arvo ei täytä sille asetettuja vaatimuksia, palautetaan tilakoodi 400. Mikäli jokin arvo asetetaan tyhjäksi, se on tyhjä merkkijono values-listassa.

Normaalitilanteessa palautetaan tilakoodi 200.

command=test-setting&plugin=account

• name – Testattavan asetuksen nimi
• value – Testattava arvo

Mikäli name ei ole username, password tai e-mail, palautetaan tilakoodi 400.

Normaalitilanteessa palautetaan seuraava olio:

{ "test-result": boolean }

name=username

Mikäli käyttäjä on kirjautuneena, palautetaan aina tilakoodi 403. Jos value on tyhjä tai varattu, palautetaan false.

Normaalitilanteessa palautetaan true.

name=password

Mikäli value ei täytä konfiguraatiotiedostossa määriteltyjä ehtoja, palautetaan false.

Normaalitilanteessa palautetaan true.

name=e-mail

Mikäli value ei täytä konfiguraatiotiedostossa määriteltyjä ehtoja, palautetaan false.

Normaalitilanteessa palautetaan true.

command=use-code&plugin=account

• code – Käytettävä koodi
• new-password – Uusi salasana (kun palautetaan salasanaa)

Etsitään Codes-taulusta tietue, jossa code esiintyy. Mikäli sellaista ei ole, palautetaan tilakoodi 400. Mikäli koodi on sidottu tiettyyn käyttäjään, joka ei ole nykyinen käyttäjä, palautetaan tilakoodi 400.

• Mikäli koodi on sähköpostin vahvistuskoodi, asetetaan käyttäjän vahvistamaton sähköpostiosoite vahvistetuksi. Tällöin Paramin tulee sisältää käyttäjän vahvistamaton sähköpostiosoite. Mikäli näin ei ole, palautetaan tilakoodi 400.

• Mikäli koodi on salasanan palautuskoodi, asetetaan käyttäjän salasanaksi new-passwordin arvo.

• Mikäli koodi on käyttöoikeuksien lisäyskoodi, myönnetään käyttäjälle koodiin sidottuun näkyvyysalueeseen Paramissa olevat oikeudet.

Normaalitilanteessa palautetaan tilakoodi 200.

User_ID	Scope_ID	Type	Param
1		0 (email)	[email protected]
1		1 (password)
	1	2 (permission)	3 (luku- ja kirjoitusoikeudet)

Huom! Koodeista siivotaan vanhentuneet pois ennen koodin käyttämistä.
Huom! Kun Type on 0 tai 1, koodi on kertakäyttöinen.

command=license&plugin=account

Palauttaa käyttäjän lisenssin, joka pitää hyväksyä ennen rekisteröintiä. Palauttaa aina seuraavan olion:

{ "license": " Lorem ipsum dolor sit amet..." }

command=send&plugin&account

• type – Lähetettävän viestin tyyppi
• username – Käyttäjätunnus lähetettäessä salasanan palautusviestiä

Lähettää viestin käyttäjän sähköpostiin.

type=confirm-email

Lähettää käyttäjän vahvistamattomaan sähköpostiin vahvistusviestin. Mikäli käyttäjä ei ole kirjautuneena, palautetaan tilakoodi 401. Mikäli käyttäjällä ei ole vahvistamatonta sähköpostia, palautetaan 400.

Normaalitilanteessa luodaan uusi vahvistuskoodi (ja poistetaan mahdollinen vanha), ja lähetetään käyttäjän vahvistamattomaan sähköpostiin vahvistusviesti. Palautetaan tilakoodi 200.

type=reset-password

Lähetetään käyttäjän vahvistettuun sähköpostiosoitteeseen palautusviesti. Mikäli ei ole olemassa annettua käyttäjää, jolla olisi vahvistettu sähköposti, palautetaan tilakoodi 400.

Normaalitilanteessa luodaan uusi vahvistuskoodi (mutta ei poisteta mahdollisia vanhoja), ja lähetetään käyttäjän vahvistettuun sähköpostiin vahvistusviesti. Palautetaan tilakoodi 200.

command=list-companies&plugin=account

• company – Yrityksen nimi
• department – Osaston nimi

Palautetaan lista kaikista yrityksistä, jotka ovat täsmälleen tai lähes samanlaisia, kuin parametreina annetut. Lista järjestetään sopivuusjärjestykseen. Mikäli company puuttuu, palautetaan kaikki yritykset.

Palautetaan aina seuraavanlainen taulukko:

[
    {
        "company": "Lorem",
        "department": "Ipsum"
    },
    {
        "company": "Lorem"
    },
    {
        "company": "Lorem",
        "department": "Ipsulamed"
    }
]