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 <[email protected]>