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 vikakoodi 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 enimmäkseen päätellään suoritettava komento.

command

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

plugin

Kun command viittaa lisäosan määrittelemään komentoon, pitää plugin parametriin laittaa lisäosan nimi. Mikäli lisäosaa ei ole, palautetaan tilakoodi 501. Mikäli löytynyt lisäosa ei määrittele commandissa pyydettyä komentoa, palautetaan tilakoodi 404.

Plugin parametri on validointijärjestyksessä ennen commandia.

Kirjautumiskäskyt

command=login

• 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 istunnolla, vanha kirjautuminen lakkaa.

Normaalitilanteessa palautetaan tilakoodi 200.

command=logout

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

command=login-test

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

Kokoonpanokäskyt

command=ui-list

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

Palauttaa luettelon kaikista asennetuista käyttöliittymistä. Palautetaan taulukkona olio kaikista 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:na

• 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

• 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

• 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 annetulle käyttöliittymälle toteuttamat lokalet.

Jokaisesta lokalesta annetaan

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

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