| 1 | | = WEB SERVICES API = |
| 2 | | |
| 3 | | (This API is also used by daemonX which drives automatic p2p syncing between clients) |
| 4 | | |
| 5 | | Supported web services:[[BR]] |
| 6 | | |
| 7 | | JSON[[BR]] |
| 8 | | JSON-RPC[[BR]] |
| 9 | | [[BR]] |
| 10 | | To do (partial work has been done):[[BR]] |
| 11 | | |
| 12 | | XML[[BR]] |
| 13 | | XML-RPC[[BR]] |
| 14 | | [[BR]] |
| 15 | | '''Service Proxy''': |
| 16 | | JSON: http://localhost:8000/sahana/admin/call/json |
| 17 | | e.g. http://localhost:8000/sahana/admin/call/json/getdata?timestamp=0&......... |
| 18 | | JSON-RPC: http://server's-ip:port/sahana/admin/call/jsonrpc |
| 19 | | replace json and jsonrpc with xml and xmlrpc respectively for xml |
| 20 | | |
| 21 | | '''Available functions''':[[BR]] |
| 22 | | '''putdata(uuid, username, password, nicedbdump):''' |
| 23 | | This function is used to insert data in the system. |
| 24 | | args: |
| 25 | | uuid (required): |
| 26 | | uuid of the machine which is calling, uuid of machine is 16 character unique string. In the case when web services client is also a Sahana instance, uuid will be generated and stored by deamonX. |
| 27 | | Username, password (required): |
| 28 | | Used for authentication purposes. Both are strings. A user must be registered at the host machine with data alteration privileges. e.g. Administrator of the system can put data in the system. |
| 29 | | nicedbdump (required): |
| 30 | | nicedbdump can be best illustrated using diagrammatically representation. If [] represents a python list then: |
| 31 | | nicedump = [ //each element of this list is another list representing a database table[[BR]] |
| 32 | | [[[BR]] |
| 33 | | table name,[[BR]] |
| 34 | | [ comma separated table attributes as string][[BR]] |
| 35 | | [ //each element in this list is a list which represents a row in table[[BR]] |
| 36 | | [comma separated row values][[BR]] |
| 37 | | [][[BR]] |
| 38 | | ..[[BR]] |
| 39 | | .. [[BR]] |
| 40 | | ][[BR]] |
| 41 | | ] [[BR]] |
| 42 | | [][[BR]] |
| 43 | | [][[BR]] |
| 44 | | ..[[BR]] |
| 45 | | ..[[BR]] |
| 46 | | ..[[BR]] |
| 47 | | ] |
| 48 | | |
| 49 | | Note that if you pass a table using nicedbdump which is not present in database, it will be simply ignored. |
| 50 | | If nicedbdump is not formated properly then an error string will be returned. Following situations will raise an error: |
| 51 | | If nicedbdump is not a list. |
| 52 | | If nicedbdump is not list of lists. |
| 53 | | Each list in nicedbdump represents a table, say n: |
| 54 | | If n does not exactly has 3 elements. |
| 55 | | If first of these three elements is not a string data type. |
| 56 | | If second of these three elements, say s, is not a list: |
| 57 | | if s in this list is not a string |
| 58 | | If third of these three elements, say t, is not a list: |
| 59 | | if each element in t is not a list, let such an element be r: |
| 60 | | if number of elements in r is not equal to number of elements in s |
| 61 | | |
| 62 | | If a table (s in the case described above) is not having 'id', 'uuid' and 'modified_on' as attribute. 'id' is unique id for each row in table. This 'uuid' is different from the 'uuid' which daemonX maintains, this is row uuid. 'modified_on' represents the last time data was modified (or created it not altered after creation) |
| 63 | | Note that only that data (referenced by row uuid) which has never life then the one in database will be added. In case of absence of that uuid in database, that data is be added. |
| 64 | | return: |
| 65 | | If user is authenticated and nicedbdump is successfully parsed, data will be added to the database and True will be returned. On the other hand, in case of error, error message will be returned as String. |
| 66 | | |
| 67 | | |
| 68 | | '''getdata(uuid, username, password, timestamp = None):''' |
| 69 | | retruns data as nicedbdump defined in putdata. Data after timestamp time will returned, if None is passes as timestamp, then that data which has been added to the system after last getdata call from uuid will be returned. |
| 70 | | Args: |
| 71 | | uuid (required): |
| 72 | | uuid of the machine which is calling, uuid of machine is 16 character unique string. In the case when web services client is also a Sahana instance, uuid will be generated and stored by deamonX. |
| 73 | | username, password (required except for local machine): |
| 74 | | Both are strings. used for authentication, user must have privileges for reading the database. If service is called from local machine (i.e. with IP 127.0.0.1) username and password are ignored and user is given access. e.g. deamonX accesses this function locally without providing username and password. |
| 75 | | Timestamp (optional): |
| 76 | | timestamp is of string type. It should be like “YYYY-MM-DD HH:MM:SS”. If timestamp = null is passes, system will automatically return data after last getdata operation between uuid and machine. deamonX uses this setting |
| 77 | | |
| 78 | | return: |
| 79 | | In case of error (like failure to authenticate), error message as string will be returned. If successful, then nicedbdump will be returned which is described above. |
| 80 | | |
| 81 | | '''Example code''':[[BR]] |
| 82 | | '''Python''':[[BR]] |
| 83 | | |
| 84 | | |
| 85 | | {{{ |
| 86 | | from jsonrpc import ServiceProxy, JSONRPCException |
| 87 | | #jsonrpc needs simplejson which we have to install first |
| 88 | | s = ServiceProxy("http://localhost:8000/sahana/admin/call/jsonrpc") |
| 89 | | try: |
| 90 | | nicedbdump = s.getdata("machinename12345","email@lums.edu.pk", "myPassword") |
| 91 | | if type(result) == str: |
| 92 | | #it means there is an error, now result has error messege |
| 93 | | pass |
| 94 | | else: |
| 95 | | #result is list type for sure, |
| 96 | | #result is nicedbdump type |
| 97 | | |
| 98 | | putit = s.putdata("machinename12345", "email@lums.edu.pk", "myPassword", nicedbdump) |
| 99 | | if putit == True: |
| 100 | | #data sucessfully sent, parsed and processes at server (but in this case no data will be added because you just queried data and sent it back) |
| 101 | | pass |
| 102 | | else: |
| 103 | | #its an error |
| 104 | | pass |
| 105 | | except JSONRPCException, e: |
| 106 | | print repr(e.error) |
| 107 | | |
| 108 | | }}} |
| 109 | | |
| 110 | | Note: |
| 111 | | You can write a client in language of your choice. |
| 112 | | |
| 113 | | Help: |
| 114 | | IRC: #sahana at freenode |
| 115 | | email: <Fran Boon> francisboon at googlemail dot com or hasanatkazmi at gmail dot com |
| 116 | | |
| 117 | | |
| 118 | | |
| 119 | | |
