Nokkis

Server API design

Server is programmed with PHP and requires Apache with Rewrite module. Messaging to and from server is implemented with XML.

NOKKIS - http://url/nokkis

GET
Return list of events
(name, url)
Return format: 

<nokkis>
    <event id="1">
        <name>Ropecon 2009</name>
        <description>Roolipelit</description>
        <startdate>1244620800</startdate>
        <enddate>1244905200</enddate>
        <num_tickets>123</num_tickets>
        <max_tickets>500</max_tickets>
    </event>
    <event id="2">
        <name>Assembly 2009</name>
        ....
    </event>
    ....
</nokkis>

POST

<nokkis>
    <event>
        <name>Ropecon 2009</name>
        <startdate>1122552</startdate>
        <enddate>842222</enddate>
        <max_tickets>3000</max_tickets>
        <apikey>897cshdsd7f89</apikey>
        <apikey>78v89sdhvsndd</apikey>
        <apikey>978v8s6vysdhj</apikey>
    </event>
</nokkis>

DELETE/PUT/POST
Not defined

CLIENT - http://url/nokkis/CLIENT/<apikey>

GET

Return valid client cache file. Includes all events and barcodes that use given apikey.  

<nokkis>
    <event id="1">
	<name>Ropecon 2009</name>
	<startdate>1234567890</startdate>
	<enddate>1238600000</enddate>
        <apikey>ABCDE12345</apikey>
        <barcode key="983475629310">
            <user>foobar@helsinki.fi</user>
            <status>1</status>
            <valid>0</valid>
        </barcode>
        <barcode key="983475629310">
            <user id="1">foobar@helsinki.fi</user>
            <status>1</status>
            <valid>0</valid>
        </barcode>
    </event>
    <event id="2">
        ...
        <barcode key="983475629310">
        ...
        </barcode>
    </event>
</nokkis> 



EVENT - http://url/nokkis/<event>

GET
Return event xml
(event real name, list of barcode ids, event start time, event end time, max tickets, list of apikeys)
Return format: 


<nokkis>
    <event id="1">
        <name>Ropecon 2009</name>
        <startdate>1122552</startdate>
        <enddate>842222</enddate>
        <num_tickets>123</num_tickets>
        <max_tickets>3000</max_tickets>
        <apikey>897cshdsd7f89</apikey>
        <apikey>78v89sdhvsndd</apikey>
        <apikey>978v8s6vysdhj</apikey>
    </event>
</nokkis>


DELETE
Delete event
Delete event if there are no actions else invalidate.
Request format: 

<nokkis>
</nokkis>

Return format: 


<nokkis>
</nokkis>

POST

Not defined

PUT
(event real name, event start time, event end time, max tickets, list of apikeys)
Return event xml

Request format: 

<nokkis>
    <event>
        <name>Ropecon 2009</name>
        <startdate>1122552</startdate>
        <enddate>842222</enddate>
        <max_tickets>3000</max_tickets>
        <apikey>897cshdsd7f89</apikey>
        <apikey>78v89sdhvsndd</apikey>
        <apikey>978v8s6vysdhj</apikey>
    </event>
</nokkis>

Return format: 


<nokkis>
</nokkis>

Error more barcodes than new value of max tickets

EVENT_LOG - http://url/nokkis/<event>/LOG

GET

Return all modifications to event
Return format: 



<nokkis>
    <event id="1">
        <action id="523456">
            <ip>62.182.115.120</ip>
            <action_time>1235553883</action_time>
            <action_data>event_modified</action_data>
        </action>
    </event>
</nokkis>

PUT/POST/DELETE

Not defined

APIKEY - http://url/nokkis/KEY

GET
Return related xml
(list of all apikeys)
Return format: 

<nokkis>
    <apikey id="11111">
        <event id="3">Ropecon 2009</event>
        <event id="4">Assembly 2008</event>
        <event id="5">Animecon 2009</event>
    </apikey>
    <apikey id="22222222222222">
        <event id="5">Animecon 2009</event>
    </apikey>
    ....
</nokkis>

APIKEY (BY EVENT) - http://url/nokkis/<event>/KEY/<key>

GET
Return related xml
(list of access using apikey)
Return format: 


<nokkis>
    <event id="873894792">
        <apikey>897cshdsd7f89</apikey>
        <apikey>78v89sdhvsndd</apikey>
        <apikey>978v8s6vysdhj</apikey>
    </event>
</nokkis>

PUT/POST/DELETE
Not defined

BARCODE - http://url/nokkis/<event>/BARCODE

POST

Create new barcode
Return new id
(owner identifier)

Request format: 

<nokkis>
</nokkis>

Return format: 
<nokkis>
    <barcode key="412158754" />
</nokkis>

or error 
<nokkis>
    <error id="41">Event full</error>
</nokkis>

GET
Get list of valid barcodes


Return format: 


<nokkis>
    <barcode key="983475629310">
        <event id="1">Ropecon 2009</event>
        <user>foobar@helsinki.fi</user>
        <status>1</status>
        <valid>0</valid>
    </barcode>
</nokkis>

or:

<nokkis>
    <event id="41215">
        <barcode key="485736457367873289" />
        <barcode key="788786878456363452" />
        <barcode key="654654747560000111" />
        <barcode key="109378663291111034" />
    </event>
</nokkis>

PUT/DELETE
Not defined

BARCODE_BY_KEY - http://url/nokkis/<event>/barcode/<key>

GET
Return barcode data by id

Request format: 

<nokkis>
</nokkis>

Return format: 


<nokkis>
    <barcode key="83475629310710">
        <event id="1">Ropecon 2009</event>
        <user id="1">foobar@helsinki.fi</user>
        <status>1</status>
        <valid>0</valid>
    </barcode>
</nokkis>

PUT
Use barcode

Return barcode data by id

Request format: 

<nokkis>
</nokkis>

Return format: 


<nokkis>
    <barcode key="98347562931071">
        <event id="1">Ropecon 2009</event>
        <user>foobar@helsinki.fi</user>
        <status>1</status>
        <valid>0</valid>
    </barcode>
</nokkis>

POST
Not defined

DELETE
Return success
Invalidate key

Request format: 

<nokkis>
</nokkis>

Return format: 


<nokkis>
</nokkis>

BARCODE_LIST - http://url/nokkis/<event>/BARCODE/LIST/<start>(,<end>)

GET

Return barcodes between id <start> and <end> 

<nokkis>
    <barcode key="98347562931071">
        <event id="1">Ropecon 2009</event>
        <user id="1">foobar@helsinki.fi</user>
        <status>1</status>
        <valid>0</valid>
    </barcode>
.....
    <barcode key="432987432897">
        <event id="1">Ropecon 2009</event>
        <user id="1">foobar@helsinki.fi</user>
        <status>1</status>
        <valid>0</valid>
    </barcode>
</nokkis>

POST/PUT/DELETE

Not defined

BARCODE_LOG - http://url/nokkis/<event>/BARCODE/LOG

GET

Return  all event barcode actions

Request format: 

<nokkis>
</nokkis>

Return format: 


<nokkis>
    <event id="1">
        <action id="0">
            <barcode key="1234128" />
            <apikey>82734728737</apikey>
            <ip>62.182.115.120</ip>
            <action_time>121</action_time>
            <action_data>barcode_used</action_data>
        </action>
        ....
        <action id="89375">
            <barcode key="29886360198278" />
            <apikey>82734728737</apikey>
            <ip>62.182.115.120</ip>
            <action_time>12355538777</action_time>
            <action_data>barcode_used</action_data>
        </action>
    </event>
</nokkis>

Returns all barcode actions in event

PUT/POST/DELETE

Not defined

Example  xml:



BARCODE_ID_LOG - http://url/nokkis/<event>/BARCODE/LOG/<start>(,<end>)


GET

Return  given barcode's actions

Request format: 

<nokkis>
</nokkis>

Return format: 


<nokkis>
    <event id="1">
        <action id="50000">
            <barcode key="99996360198278" />
            <apikey>82734728737</apikey>
            <ip>62.182.115.120</ip>
            <action_time>128777</action_time>
            <action_data>barcode_used</action_data>
        </action>
        <action id="89375">
            <barcode key="29886360198278" />
            <apikey>82734728737</apikey>
            <ip>62.182.115.120</ip>
            <action_time>12355538777</action_time>
            <action_data>barcode_used</action_data>
        </action>
    </event>
</nokkis>

PUT/POST/DELETE

Not defined

Error-handling

- Command/event (error code): Explanation
- All commands (1): Server couldn't connect to database
- All commands (2): Internal database error
- All commands (3): Invalid xml input
- All commands (10): Insufficient privileges
- All commands (11): Invalid apikey
- EVENT PUT/POST (20): Invalid name
- EVENT PUT/POST (21): End time before start time
- EVENT GET/PUT/DELETE (22): Event doesn't exist
- EVENT PUT/POST (23): Apikeys must be alphanumeric
- EVENT GET (24): Event not found
- APIKEY GET (30): Apikey not found
- BARCODE GET & BARCODEBYKEY GET/PUT/DELETE (40): Barcode not found
- BARCODE POST (41): Event full
- BARCODE POST (42): Event doesn't exist
- BARCODEBYKEY PUT (43): Barcode is already used
- BARCODEBYKEY PUT (44): Invalid barcode
- BARCODEBYKEY PUT (45): Event hasn't started yet
- BARCODEBYKEY PUT (46): Event has already ended
- BARCODELIST & BARCODEIDLOG GET (50): Start before end

Return format: 

<nokkis>
    <error id="24">Event not found</error>
<nokkis>