Terminaalin API v2

Terminaalin ainoa kutsukelpoinen skripti on terminal/index.php, joka vaatii HTTPS-protokollan. Mikäli protokolla ei ole HTTPS, palautetaan HTTP:n tilakoodi 503 Forbidden.

Terminaalin sisäinen suoritusjärjestys

1. index.php vastaanottaa Ajaxilla tehdyn pyynnön ja ohjaa sen CommandSwitcherille.
2. CommandSwitcher päättelee, mikä komento on kyseessä ja suorittaa sen. Jos komentoa ei voitu tunnistaa, se ei ollut kelvollinen tai sen aikana tapahtui odottamaton virhe, CommandSwitcher käsittelee virheen.
3. AbstractCommand tarkistaa, että komentoa pyydetään tuetulla HTTP:n metodilla ja suorittaa varsinaisen komennon. Mikäli komentoa kutsutaan kielletyllä metodilla, AbstractCommand keskeyttää suorituksen virheeseen. AbstractCommand osaa myös ilmoittaa pyydettäessä, mitä metodeja komento tukee.
4. Varsinainen komento tekee esitarkistuksia, suorittaa tehtävänsä ja palauttaa sen tulokset.

Kaikille komennoille yhteiset vaatimukset

• Komennon tiedoston pitää olla terminal/commands-hakemistossa.
• Tiedoston nimen pitää olla kokonaan kirjoitettu pienillä kirjaimilla ja sananvaihdot korvattu tavuviivoilla (-). Esim. login.php tai login-test.php.
• Tiedoston sisällä pitää olla PHP:n luokka, jonka nimi on sama kuin tiedoston nimi (ilman tiedostopäätettä). Jokaisen sanan ensimmäinen kirjain pitää olla iso kirjain, muut pienellä ja sananvaihdot poistettu. Esim. Login tai LoginTest.
• Luokan pitää toteuttaa Command-rajapinta. Joitakin mahdollisia poikkeuksia lukuun ottamatta tämä tapahtuu perimällä AbstractCommand-luokka, joka toteuttaa vaaditun rajapinnan. Eli ilman erikoista syytä komennon luokan pitää periä AbstractCommand-luokka.

Esimerkkejä komentojen tiedostojen nimistä ja luokkien nimistä

Tiedoston nimi	Luokan nimi
sample-command.php	SampleCommand
diff-text.php	DiffText
save.php	Save

Tässä on komennon vaatimukset täyttävä malli: terminal/commands/malli-komento.php

<?php

// Varmistetaan tarvittavien tiedostojen saanti.
// Huom. Load-file antaa ladata vain terminal-hakemiston alla olevia
// tiedostoja. (Poista tämä ja edellinen rivi.)
load_file("abstract-command.php");

/**
 * Tässä kerrotaan, mitä komento tekee. (Poista tämä rivi.)
 * 
 * @author [tähän pilkulla erotettu lista tiedoston päämuokkaajista]
 */
class MalliKomento extends AbstractCommand {

    /**
     * Luo ilmentymän komennosta sallituilla komennoilla.
     */
    public function __construct() {
        // Tämä komento sallii käytettävän HEAD- ja GET-metodeja.
        // (Poista tämä ja edellinen rivi.)
        parent::__construct(array("HEAD", "GET"));
    }

    /**
     * Suorittaa komennon.
     * 
     * @return void 
     */
    protected function execute_command() {
        // Tässä kohdassa suoritetaan komento. (Poista tämä rivi.)
    }

}

Vinkki lisäosien komennoille

Lisäosien komennot sijaitsevat hakemistossa plugins/pluginin-nimi/commands, eivät terminal/commands -hakemistossa, kuten edellä vaadittiin. Ongelma saadaan poistettua laittamalla terminal/commands -hakemistoon vaadittu tiedosto, mutta sen sisällöksi seuraava:

<?php

// Varmistetaan tarvittavien tiedostojen saanti.
// Huom. Tässä ei voida käyttää load_file-funktiota, koska se ei salli
// lataamista terminal-hakemiston ulkopuolelta. (Poista huomautus.)
require_once '../../plugins/pluginin-nimi/commands/komennon-nimi.php';

Testaus

Terminaalin API:n jokaisesta komennosta tehdään yksikkötestit, samoin kuin useamman komennon kutsusarjoista. Kaikki testit löytyvät hakemistosta test/unit/terminal/commands. Testeissä käytetään QUnit-testityökalua.

Vikakoodit

Vikakoodit, joita käytetään vastauksen Error-code-otsakkeessa, 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.

Kirjautumiskomennot

Kirjautumiskomennot hoitavat sisään- ja uloskirjautumiset sekä kirjautuneisuuden testaamisen.

Sisäänkirjautuminen

HEAD /login HTTP/1.1

Parametrit

user string - Käyttäjätunnus. Pakollinen.
password string - Salasana. Pakollinen.

• Mikäli kirjautuminen onnistui, tulos on:

HTTP/1.1 204 No Content
Logged-in: true

• Mikäli kirjautuminen epäonnistui:

HTTP/1.1 400 Bad Request
Logged-in: boolean
Error-code: string

Logged-in

true, mikäli samassa istunnossa oltiin kirjautuneena jo aiemmin.
false, mikäli samassa istunnossa ei oltu kirjautuneena jo aiemmin.

Error-code

1-user, mikäli käyttäjätunnus puuttuu.
1-password, mikäli salasana puuttuu.
2-user, mikäli tunnusta ei ole olemassa.
2-password, mikäli salasana on väärä.

Uloskirjautuminen

HEAD /logout HTTP/1.1

• Uloskirjautumisen tulos on:

HTTP/1.1 204 No Content
Logged-in: false

Kirjautuneisuuden testaaminen

HEAD /login-test HTTP/1.1

• Kirjautuneisuuden testaamisen tulos on:

HTTP/1.1 204 No Content
Logged-in: boolean

Logged-in

true, mikäli samassa istunnossa oltiin kirjautuneena.
false, mikäli samassa istunnossa ei oltu kirjautuneena.

Tilinhallintakomennot

Tilinhallintakomennot hoitavat tilin luonnin ja poiston sekä tilin tietojen haun ja päivittämisen.

Tilin luominen

PUT /account HTTP/1.1
Test: boolean

Parametrit

user 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.

• Mikäli Test-otsakkeen arvo oli true ja tilin luominen onnistuisi:

HTTP/1.1 204 No Content
Test: true

• Mikäli tilin luominen onnistui:

HTTP/1.1 201 Created

• Mikäli jokin annettu tieto ei täyttänyt sille asetettuja ehtoja:

HTTP/1.1 400 Bad Request
Error-code: string

Error code

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-user, 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.

Tilin poistaminen

DELETE /account HTTP/1.1

• Mikäli tilin poistaminen onnistui:

HTTP/1.1 200 OK

• Mikäli käyttäjä ei ollut kirjautuneena:

HTTP/1.1 403 Forbidden

Tilin tietojen haku

GET /account/ HTTP/1.1

Parametrit

field-names lista - Pyydettyjen kenttien nimet pilkulla erotettuna listana. Vaihtoehtoja ovat user, email, verified-email, name, company ja department. Esim. user,email.

• Mikäli tietojen haku onnistui:

HTTP/1.1 200 OK

{
  "user": 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 Forbidden

Tilin tietojen päivittäminen

PATCH /account HTTP/1.1
Test: boolean

Parametrit

email 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.

Vain ne tiedot välitetään (yksi tai useampi), jotka päivitetään.

• Mikäli Test-otsakkeen arvo oli true ja tietojen päivittäminen onnistuisi:

HTTP/1.1 204 No Content
Test: true

• 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 jokin annettu tieto ei täyttänyt sille asetettuja ehtoja:

HTTP/1.1 400 Bad Request
Error-code: string

Error-code

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.

Tilin salasanan vaihtaminen

PATCH /account/change-password HTTP/1.1

Parametrit

old-password string - Vanha salasana. Pakollinen.
new-password string - Uusi salasana. Pakollinen.

• Mikäli salasanan vaihtaminen onnistui:

HTTP/1.1 204 No Content
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

Error-code

1-oldpassword, mikäli vanha salasana puuttui.
1-newpassword, mikäli uusi salasana puuttui.
2-oldpassword, mikäli vanha salasana ei ollut kirjautuneen käyttäjän salasana.
2-newpassword, mikäli uusi salasana ei täyttänyt sille asetettuja vaatimuksia.