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

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, tekee 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ä). Siinä kaikkien sanojen ensimmäiset kirjaimet pitää olla kirjoitettuna isoilla kirjaimilla 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.
require_once '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ä 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.
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.

Kirjautumiskomennot

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

Sisäänkirjautuminen

HEAD /login/:käyttäjätunnus/:salasana HTTP/1.1

• 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: int

Mikäli samassa istunnossa oltiin kirjautuneena jo aikaisemmin, Logged-in on true, muuten false.

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

Mikäli samassa istunnossa oltiin kirjautuneena, Logged-in on true, muuten false.

Tilinhallintakomennot

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

Tilin luominen

PUT /account/:käyttäjätunnus/:salasana HTTP/1.1

{
  "email": string,
  "name": string,
  "company": string,
  "department": string
}

Pyynnön sisällössä välitetyt ominaisuudet, eli sähköpostiosoite, oikea nimi, yritys ja sen osasto, ovat oletuksena vapaaehtoisia. Ne voidaan määritellä pakollisiksi konfiguroimalla.

• 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: int

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/:kenttien-nimet HTTP/1.1

Kenttien nimet on pilkulla erotettu lista pyydettyjen tietojen nimiä. Esim. user,email.

• Mikäli tietojen haku onnistui:

HTTP/1.1 200 OK

{
  "user": string,
  "email": string,
  "confirmed-email": string,
  "name": string,
  "company": string,
  "department": string
}

Vastauksessa 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

{
  "email": string,
  "name": string,
  "company": string,
  "department": string
}

Vain ne tiedot välitetään, jotka pitäisi päivittää.

• Mikäli tietojen päivittäminen onnistui:

HTTP/1.1 204 No Content

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

HTTP/1.1 400 Bad Request
Error-code: int

Salasanan vaihtaminen

PATCH /account HTTP/1.1

{
  "new-password": string,
  "old-password": string
}

• Mikäli salasanan vaihtaminen onnistui:

HTTP/1.1 204 No Content

• Mikäli salasanan vaihtaminen epäonnistui:

HTTP/1.1 400 Bad Request
Error-code: int