[TPG] Misc changes for new dispense
[zanchey/dispense2.git] / sql-edition / api / API.txt
1  API for the new dispense
2 -------------------------
3
4 New dispense is written in entirely in postgresql. The server does all the
5 required processing, meaning that database integrity is always maintained.
6
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
10 stdin/stdout.
11
12 The details for connecting to the database are:
13     hostname: dispense.ucc.gu.uwa.edu.au
14     username: anondispense
15     database: dispense
16
17 No password is required. You will only be able to connect from 'trusted'
18 machines - currently this is mussel, mermaid, morwong.
19
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.
22
23 The useful things can be done once connected:
24
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
32           account balance.
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
37                   coke group.
38         * service_name is the name of the service as seen in the services
39           table.
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
42           table.
43
44 Example follows:
45
46 $ psql dispense -U anondispense -h dispense.ucc.gu.uwa.edu.au
47 \Welcome to psql 7.4.1, the PostgreSQL interactive terminal.
48
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
53        \q to quit
54
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 -------------+-----------------+--------------------------------------+------------
60  nothing     |                 |                                      |           
61  give        |                 | <username> <cents>                   |           
62  acct        |                 | <cents> <reason>                     |           
63  passion pop |              80 |                                      |          8
64  vb          |              80 |                                      |          0
65  emu export  |              80 |                                      |          3
66  champagne   |              80 |                                      |          9
67  coke powder |              80 |                                      |         11
68  update_coke |                 | <slot number> <new name> <new price> |           
69  opendoor    |                 |                                      |           
70  grape juice |              80 |                                      |          0
71  some foo    |              77 |                                      |          3
72 (12 rows)
73
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 -----------+--------------------+--------------------
80  dagobah   |              -5080 |                  0
81 (1 row)
82
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
88
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']);
92  do_request 
93 ------------
94  t
95 (1 row)
96
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 -----------+--------------------+--------------------
101  dagobah   |               4920 |                  0
102 (1 row)
103
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
108
109 -- Try that dispense again, but we see there is none
110 dispense=> select do_request('dagobah', 'some foo', NULL);
111  do_request 
112 ------------
113  t
114 (1 row)
115
116 -- Updating a slot name/price on the coke machine
117 dispense=> select do_request('dagobah', 'update_coke', array['3', 'orange blah', '88']);
118  do_request 
119 ------------
120  t
121 (1 row)
122
123 -- Note the services have changed
124 dispense=> select * from get_services('dagobah');
125   item_name  | item_cost_cents |             item_syntax              | item_stock 
126 -------------+-----------------+--------------------------------------+------------
127  nothing     |                 |                                      |           
128  give        |                 | <username> <cents>                   |           
129  acct        |                 | <cents> <reason>                     |           
130  passion pop |              80 |                                      |          8
131  vb          |              80 |                                      |          0
132  emu export  |              80 |                                      |          3
133  champagne   |              80 |                                      |          9
134  coke powder |              80 |                                      |         11
135  update_coke |                 | <slot number> <new name> <new price> |           
136  opendoor    |                 |                                      |           
137  grape juice |              80 |                                      |          0
138  orange blah |              88 |                                      |          3
139 (12 rows)
140
141 Email comments or queries to <dagobah@ucc.asn.au>

UCC git Repository :: git.ucc.asn.au