X-Git-Url: https://git.ucc.asn.au/?p=zanchey%2Fdispense2.git;a=blobdiff_plain;f=sql-edition%2Fapi%2FAPI.txt;fp=sql-edition%2Fapi%2FAPI.txt;h=e3ab07f8079c92d0f39df46b21a8984d7739dcaa;hp=0000000000000000000000000000000000000000;hb=2b7498ef0aedc319f95d3b5994e7ac6ac5d4c8ee;hpb=356135846736fc057fec0c30dc272dd59712b2bb diff --git a/sql-edition/api/API.txt b/sql-edition/api/API.txt new file mode 100644 index 0000000..e3ab07f --- /dev/null +++ b/sql-edition/api/API.txt @@ -0,0 +1,141 @@ + API for the new dispense +------------------------- + +New dispense is written in entirely in postgresql. The server does all the +required processing, meaning that database integrity is always maintained. + +The current interface for dispense is using a postgresql client library. +Client libraries exist for many languages including C, C++, Perl, Python, +Ruby, PHP, or you could also speak with the supplied client 'psql' through +stdin/stdout. + +The details for connecting to the database are: + hostname: dispense.ucc.gu.uwa.edu.au + username: anondispense + database: dispense + +No password is required. You will only be able to connect from 'trusted' +machines - currently this is mussel, mermaid, morwong. + +Note the API still isn't stable - it'd be worth running these commands by hand +to see what the resulting tables look like. + +The useful things can be done once connected: + + - SELECT * FROM get_services(username) + will give you a list of services available to the given user, including + syntax if parameters are required + - SELECT get_balance() + will return a table of all users and their balances. + - SELECT get_balance(username) + will return a table with one row for the given user, displaying their + account balance. + - SELECT do_request(target_user, service_name, parameters) + will perform a request. + * target_user is the user you wish to perform the request upon. + You will only be permitted to act on somebody else if you are in the + coke group. + * service_name is the name of the service as seen in the services + table. + * parameters is an array of parameters for the service, if required. + These should appear in the order as item_syntax from the services + table. + +Example follows: + +$ psql dispense -U anondispense -h dispense.ucc.gu.uwa.edu.au +\Welcome to psql 7.4.1, the PostgreSQL interactive terminal. + +Type: \copyright for distribution terms + \h for help with SQL commands + \? for help on internal slash commands + \g or terminate with semicolon to execute query + \q to quit + +-- Equivalent of bringing up the menu. Only items allowed for +-- the given user are shown. +dispense=> select * from get_services('dagobah'); + item_name | item_cost_cents | item_syntax | item_stock +-------------+-----------------+--------------------------------------+------------ + nothing | | | + give | | | + acct | | | + passion pop | 80 | | 8 + vb | 80 | | 0 + emu export | 80 | | 3 + champagne | 80 | | 9 + coke powder | 80 | | 11 + update_coke | | | + opendoor | | | + grape juice | 80 | | 0 + some foo | 77 | | 3 +(12 rows) + +-- Get balance for a user. +-- Equivalent of 'dispense acct dagobah' +-- Calling just get_balance() will return all users balances. +dispense=> select * from get_balance('dagobah'); + user_name | user_balance_cents | user_balance_bytes +-----------+--------------------+-------------------- + dagobah | -5080 | 0 +(1 row) + +-- Dispense something for a user. +-- Equivalent of 'dispense -u dagobah grape juice' +dispense=> select do_request('dagobah', 'grape juice', NULL); +ERROR: You may not dispense below -$20.00. +CONTEXT: PL/pgSQL function "do_request" line 12 at SQL statement + +-- Adjust somebody's account balance up or down. +-- Equivalent of 'dispense acct dagobah +10000 BAG123' +dispense=> select do_request('dagobah', 'acct', array['+10000', 'BAG123']); + do_request +------------ + t +(1 row) + +-- Get the balance once again ... note that it's higher :) +dispense=> select * from get_balance('dagobah'); + user_name | user_balance_cents | user_balance_bytes +-----------+--------------------+-------------------- + dagobah | 4920 | 0 +(1 row) + +-- Try that dispense again, but we see there is none +dispense=> select do_request('dagobah', 'grape juice', NULL); +ERROR: We are out of stock of that item. +CONTEXT: PL/pgSQL function "do_request" line 12 at SQL statement + +-- Try that dispense again, but we see there is none +dispense=> select do_request('dagobah', 'some foo', NULL); + do_request +------------ + t +(1 row) + +-- Updating a slot name/price on the coke machine +dispense=> select do_request('dagobah', 'update_coke', array['3', 'orange blah', '88']); + do_request +------------ + t +(1 row) + +-- Note the services have changed +dispense=> select * from get_services('dagobah'); + item_name | item_cost_cents | item_syntax | item_stock +-------------+-----------------+--------------------------------------+------------ + nothing | | | + give | | | + acct | | | + passion pop | 80 | | 8 + vb | 80 | | 0 + emu export | 80 | | 3 + champagne | 80 | | 9 + coke powder | 80 | | 11 + update_coke | | | + opendoor | | | + grape juice | 80 | | 0 + orange blah | 88 | | 3 +(12 rows) + +Email comments or queries to