1 API for the new dispense
2 -------------------------
4 New dispense is written in entirely in postgresql. The server does all the
5 required processing, meaning that database integrity is always maintained.
7 The current interface for dispense is using a postgresql client library.
8 Client libraries exist for many languages including C, C++, Perl, Python,
9 Ruby, PHP, or you could also speak with the supplied client 'psql' through
12 The details for connecting to the database are:
13 hostname: dispense.ucc.gu.uwa.edu.au
14 username: anondispense
17 No password is required. You will only be able to connect from 'trusted'
18 machines - currently this is mussel, mermaid, morwong.
20 Note the API still isn't stable - it'd be worth running these commands by hand
21 to see what the resulting tables look like.
23 The useful things can be done once connected:
25 - SELECT * FROM get_services(username)
26 will give you a list of services available to the given user, including
27 syntax if parameters are required
28 - SELECT get_balance()
29 will return a table of all users and their balances.
30 - SELECT get_balance(username)
31 will return a table with one row for the given user, displaying their
33 - SELECT do_request(target_user, service_name, parameters)
34 will perform a request.
35 * target_user is the user you wish to perform the request upon.
36 You will only be permitted to act on somebody else if you are in the
38 * service_name is the name of the service as seen in the services
40 * parameters is an array of parameters for the service, if required.
41 These should appear in the order as item_syntax from the services
46 $ psql dispense -U anondispense -h dispense.ucc.gu.uwa.edu.au
47 \Welcome to psql 7.4.1, the PostgreSQL interactive terminal.
49 Type: \copyright for distribution terms
50 \h for help with SQL commands
51 \? for help on internal slash commands
52 \g or terminate with semicolon to execute query
55 -- Equivalent of bringing up the menu. Only items allowed for
56 -- the given user are shown.
57 dispense=> select * from get_services('dagobah');
58 item_name | item_cost_cents | item_syntax | item_stock
59 -------------+-----------------+--------------------------------------+------------
61 give | | <username> <cents> |
62 acct | | <cents> <reason> |
63 passion pop | 80 | | 8
67 coke powder | 80 | | 11
68 update_coke | | <slot number> <new name> <new price> |
70 grape juice | 80 | | 0
74 -- Get balance for a user.
75 -- Equivalent of 'dispense acct dagobah'
76 -- Calling just get_balance() will return all users balances.
77 dispense=> select * from get_balance('dagobah');
78 user_name | user_balance_cents | user_balance_bytes
79 -----------+--------------------+--------------------
83 -- Dispense something for a user.
84 -- Equivalent of 'dispense -u dagobah grape juice'
85 dispense=> select do_request('dagobah', 'grape juice', NULL);
86 ERROR: You may not dispense below -$20.00.
87 CONTEXT: PL/pgSQL function "do_request" line 12 at SQL statement
89 -- Adjust somebody's account balance up or down.
90 -- Equivalent of 'dispense acct dagobah +10000 BAG123'
91 dispense=> select do_request('dagobah', 'acct', array['+10000', 'BAG123']);
97 -- Get the balance once again ... note that it's higher :)
98 dispense=> select * from get_balance('dagobah');
99 user_name | user_balance_cents | user_balance_bytes
100 -----------+--------------------+--------------------
104 -- Try that dispense again, but we see there is none
105 dispense=> select do_request('dagobah', 'grape juice', NULL);
106 ERROR: We are out of stock of that item.
107 CONTEXT: PL/pgSQL function "do_request" line 12 at SQL statement
109 -- Try that dispense again, but we see there is none
110 dispense=> select do_request('dagobah', 'some foo', NULL);
116 -- Updating a slot name/price on the coke machine
117 dispense=> select do_request('dagobah', 'update_coke', array['3', 'orange blah', '88']);
123 -- Note the services have changed
124 dispense=> select * from get_services('dagobah');
125 item_name | item_cost_cents | item_syntax | item_stock
126 -------------+-----------------+--------------------------------------+------------
128 give | | <username> <cents> |
129 acct | | <cents> <reason> |
130 passion pop | 80 | | 8
132 emu export | 80 | | 3
134 coke powder | 80 | | 11
135 update_coke | | <slot number> <new name> <new price> |
137 grape juice | 80 | | 0
138 orange blah | 88 | | 3