Moya Rest API

Rest API:a voi käyttää kahdella tavalla:

• Antamalla apille käyttäjätunnuksen ja ohjelmakohtaisen salasanan jonka käyttäjä voi revoikoida halutessaan. Soveltuu esimerkiksi paikkakarttamuokkaimeen, tai vastaavaan jossa käyttäjä pystyy antamaan ohjelmistolle tietoja. Kaikilla rajapinnan läpi tehdyillä kyselyillä on samat oikeudet kuin käyttäjätunnuksen käyttäjällä.
• Ilmoittautumalla rajapinnalle jolloin tapahtuman järjestäjä voi hyväksyä kyselyn lähettäjän. Tällöin kyselyt tehdään kirjautumattomalla käyttäjällä ja kaikki rajapinnan kyselyt eivät ole käytettävissä. Soveltuu esimerkiksi erilaisten lukijoiden (RFID, viivakoodi) käyttöön.

Random

Unix timestamp esim arduinoille, ym: /MoyaWeb/currenttime

Lukijat

• Lisää eventin (ei tarvi authia) GET: /MoyaWeb/shop/rfidListener.jsf?reader=plaa&tag=plaa
• Listaa lukijat: GET: /MoyaWeb/rest/reader/List
• Listaa kaikkien lukijoiden viimeiset tapahtumat: /MoyaWeb/rest/reader/LastEventusers
• Hae lukijan tapahtumat /MoyaWeb/rest/reader/readerevents/{readerId}/{eventId} Jos eventId == 0, palauta viimeiset 20 tapahtumaa, Jos eventId < 0 palauta kaikki tapahtumat.

Korttitulostus

• Listaa kaikki kortit: GET /MoyaWeb/rest/card/ListAll
• Listaa kaikki tulostamattomat kortit: GET: /MoyaWeb/rest/card/ListUnprinted
• Hae tulostettava kortti: GET /MoyaWeb/rest/card/Get/{cardId}
• Hae tulostettava kortti PNG:nä: GET: /MoyaWeb/rest/card/GetImage/{cardId}
• Varaa kortti tulostukseen /MoyaWeb/rest/card/Reserve/{cardId}
• Merkitse kortti Tulostetuksi /MoyaWeb/rest/card/Printed/{cardId}
• Hae käyttäjän kortti: GET: /MoyaWeb/rest/user/card/{eventuserId}

Paikkojen hallinta

• Näytä tapahtuman kartat: GET /MoyaWeb/rest/placeadmin/maps
• Näytä kartan paikat: GET /MoyaWeb/rest/placeadmin/places/{mapId}
• Hae kartan taustakuva: /placeadmin/background/{mapId}
• Poista paikka: DELETE /MoyaWeb/rest/placeadmin/place/{id}
• Muokkaa paikkaa: PUT /MoyaWeb/rest/placeadmin/place/{id}
• Luo paikka: POST /MoyaWeb/rest/placeadmin/place
• Vapauta paikka: PUT /MoyaWeb/rest/placeadmin/place/{placeId}/release
• Varaa paikka: PUT /MoyaWeb/rest/placeadmin/place/{placeId}/reserve/{eventuserId}

luonti ja muokkaus ottavat vastaan json olion (päivityksessä mapId:tä ei tarvita) Päivityksessä mikään kenttä ei ole pakollinen.

{
    "name": "X21",
    "mapX": 486,
    "mapY": 60,
    "width": 18,
    "height": 14,
    "buyable": true,
    "disabled": false,
    "productId": 262,
    "mapId": 5
}

Olioiden metadata

PrintedCard toteutettu. Uudet tyypit täytyy erikseen lisätä koodiin.

• Hae PrintedCard-entiteetin koko metadata JSON-oliona: GET: /MoyaWeb/rest/meta/v1/printedcard/${printedCardId}
• Hae metadatasta yksittäinen haara JSON-oliona: GET: /MoyaWeb/rest/meta/v1/printedcard/${printedCardId}/${module...}
• Aseta metadataan yksittäinen haara: POST: /MoyaWeb/rest/meta/v1/printedcard/${printedCardId}/${module...}
• GET: /MoyaWeb/rest/meta/v1/printedcard/${printedCardId}/${path...}
• PUT/POST: /MoyaWeb/rest/meta/v1/printedcard/${printedCardId}/${path...}
• GET: /MoyaWeb/rest/meta/v1/eventuser/${eventUserId}/${path...}
• PUT/POST: /MoyaWeb/rest/meta/v1/eventuser/${eventUserId}/${path...}
• GET: /MoyaWeb/rest/meta/v1/user/${userId}/${path...}
• PUT/POST: /MoyaWeb/rest/meta/v1/user/${userId}/${path...}

Käyttäjät

• Authenticate user: POST /MoyaWeb/rest/user/auth
  • Form params: username, password
• Check user password: POST /MoyaWeb/rest/user/check-password
  • Form params: username, password
  • Returns status 200 if ok.
• Get user info: GET /MoyaWeb/rest/user?login=foo&email=bar
  • Query params: email, login (all are optional, can use any one)
  • Returns: EventUser JSON
• Set place given status: POST /MoyaWeb/rest/user/giveplace/${placeId} (formparam action = give / ungive)
• GET /MoyaWeb/rest/user/reservationswithcode/{code}
• POST /MoyaWeb/rest/user/giveplace/{placeId}
  • Form params: action
• GET /MoyaWeb/rest/user/reservationswithcode/{code}
• GET /MoyaWeb/rest/user/{userid}/reservations
• GET /MoyaWeb/rest/user/eventusers
• GET /MoyaWeb/rest/user/card/{eventuserId}

Rest-kyselyn varmentaminen

Käyttäjäkohtainen kirjautuminen

Jokaisen kyselyn mukana tulee lähettää seuraavat GET-parametrit:

• appkey - Applikaatiokohtainen avain
• appuser - Käyttäjä- tai laitekohtainen applikaatioavain
• appstamp - Kasvava numeerinen arvo - esimerkiksi Epoch-timestamp
• appmac - Kyselyosoitteesta sekä ylläolevista laskettava SHA1 tarkistesumma.

appmac lasketaan seuraavasti: {pathinfo}+{appkey}+{appuser}+{appstamp}+{user-secret-key}

Jos oletetaan että ylläolevilla muuttujilla on arvot

• appkey=abcdefg
• appuser=testuser-asdf
• appstamp=1393735570144
• ja rest-kyselyn koko osoite on /MoyaWeb/MoyaWeb/rest/placeadmin/places/30
• ja käyttäjän salainen avain on acdcabbacd.

Tällöin SHA1 tarkistesumma lasketaan tekstistä:

/placeadmin/places/30+abcdefg+testuser-asdf+1393735570144+acdcabbacd

eli tarkistesumma on caf96ad97a356b90925c34f28c92d303efa87432, jolloin rest-kysely on:

/MoyaWeb/MoyaWeb/rest/placeadmin/places/30?appkey=abcdefg&appuser=testuser-asdf&appstamp=1393735570144&appmac=caf96ad97a356b90925c34f28c92d303efa87432

Design-periaatteet

Operaatiot

• GET: Hae listaa tai hae asioita. GET ei saa aiheuttaa muutoksia! (GET /resurssi => [{"id":1},{"id":2},...], GET /resurssi/1 => {"id":1, "name":"foo"})
• PUT: Aseta tai korvaa jokin tietyssä polussa tietyllä id:llä oleva asia (PUT /resurssi/1 {"name":"plop"})
• POST: Uuden luonti sekä muut operaatiot (POST /resurssi {"name":"uusi"} => {"id":24, "name":"uusi"})
• DELETE: Poista jotain (DELETE /resurssi/25)