.. RESTCAT APIdocumentation master file, created by sphinx-quickstart on Wed Mar 10 10:52:08 2010. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. .. toctree:: :maxdepth: 2 API Reference ============= This is the API reference for RESTCat. RESTCat is a RESTFul API so it can be accessed from almost any system or programming language capable of making a web request. We will use 'curl', a command line HTTP client to demonstrate API calls, but this can also be done directly from code. A number of RESTCat client examples can be found in the python-omhe_ library. .. _python-omhe: http://github.com/videntity/python-omhe The following sections outline users, trust relationships, creating transactions, and querying results. Understanding the User Data Model ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These are the fields for users. In order to create a user via the API, you must have the can_create_users permission. You set this inside the admin (http://127.0.0.1:8000/admin) ============================ ======== ================================================================ Fields Required Details ============================ ======== ================================================================ username Y Text. Must be unique first_name Y Text. last_name Y Text. email Y Text. Valid email. Must be unique. password Y Text. pin Y Numeric text. Length must = 4. gender Y Text (See gender choices). height_in Y Numeric text. Integer. weight_goal Y Numeric text. Float or integer. birthdate Y Text in format YYYY-MM-DD phone_number N Numeric text. Length must be 10 or 11. US numbers Only. mobile_phone_number N Numeric text. Length must be 10 or 11. US numbers Only. fax_number N Numeric text. Length must be 10 or 11. US numbers Only. organization N Text. twitter N Text. health_score N Text. steps_per_day_goal N Integer text. Default = 10000. rubies Y* Integer. Default=1. Cannot be changed directly by clients. checkins Y* Integer. Default=1. Cannot be changed directly by normal users. score Y* Integer. Default=1. Cannot be changed directly by normal users. points Y* Integer. Default=1. Cannot be changed directly by normal users. vid Y* Text. 15 char numeric only. Auto-generated if not supplied ============================ ======== ================================================================ The following are valid values for gender. =================================== === Valid Gender Types =================================== === female male transgender_male_to_female transgender_female_to_male sexual_reassignment_male_to_female sexual_reassignment_female_to_male =================================== === Understanding the Transaction Data Model ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Below is a table describing the reserved fields in the Transaction Data Model. This data model is based on the MUESLI specification. http://code.google.com/p/muesli ========== === ====================== ==== ====== ======= =================================================================== FIELD REQ DESCRIPTION TYPE MIN MAX RESTRICTIONS ========== === ====================== ==== ====== ======= =================================================================== id Yes TransactionID CHAR 40 40 Must be a UUID ev_dt Yes Event DateTime CHAR 17 17 Must be UTC time and end in the letter 'z' or 'u' YYYYMMDD::HHMMSSu ev_tz Yes Event TimezoneOffset CHAR 1 6 -12:00 > tzo > +14:00 tx_dt Yes Transaction DateTime CHAR 17 17 Must be UTC time and end in the letter 'z' or 'u' YYYYMMDD::HHMMSSz tx_tz Yes Tx TimezoneOffset CHAR 1 6 -12:00 > tzo > +14:00 sndr Yes SenderID CHAR 1 15 No special characters except -, _, , rcvr Yes ReceiverID CHAR 1 15 No special characters except -, _, ,. subj Yes SubjectID CHAR 1 15 No special characters except -, _, ,. txidr No TransactionIDReference CHAR 40 40 Must be a UUID of a past transaction rev No Revision CHAR 1 5 INIMITABLE. Generated by Server hid No HardwareID CHAR 1 40 omhe No OMHE CHAR 1 5 note No Note CHAR 1 307 name No TransactionName CHAR 1 30 fee No Fee CHAR 1 10 Must contain only numbers or '.' currency No Currency CHAR 3 3 See CURRENCY_CHOICES sec No SecurityLevel CHAR 1 1 See SECURITY_CHOICES cert No Certificate CHAR 1 1024 mime No MIMEType CHAR 1 255 Must be a valid MIMEType ttype No TransactionType CHAR 1 10 See TRANSACTION_CHOICES urld No URLDescription CHAR 5 2048 Must be a valid URL urli No URLItem CHAR 1 2048 Must be a valid URL texti No TextItem CHAR 1 2048 Must be ASCII text. created_on No CreatedOn CHAR 17 17 INIMITABLE. Generated by the Server ========== === ====================== ==== ====== ======= ============================================================== .. _UUID::http://en.wikipedia.org/wiki/Universally_Unique_Identifier Other Important Transaction Metadata: ************************************* If you supply values for SecurityLevel, Currency, or Type the values should be a value in the dictionaries below. The currency and transaction choices is expected to expand. SECURITY_CHOICES: :: { '0":"Undefined (Default)", "1":"Low", "2":"Medium", "3":"High" } CURRENCY_CHOICES :: { 'usd':'US Dollar' 'can':'Canadian Dollar' 'eur':'Euro' 'mex':'Mexican Pesos' } TRANSACTION_CHOICES :: { "pdf":"pdf", "ccr":"ccr", "ccd","ccd", "indivo":"indivo", "hdata":"hdata", "png": "png", "jpg":"jpg", "bmp": "bmp", "tiff": "tiff", "png": "png", "jpeg200": "jpeg200", "word_doc": "word_doc", "text":"text", "tweet":"tweet", "snomedct": "snomedct", "hl7v2": "hl7v2", "hl7v3": "hl7v3", "unk":"unk", "icd9":"icd9", "icd10":"icd10", "cpt":"cpt", "hicpcs":"hicps", "loinc":"loinc", "lab":"lab", "rx":"rx", "rxnorm":"rxnorm, "diacom_image": "diacom_image", "diacom_structured_report":"diacom_structured_report", "x10":"x10", "idc": "idc", "fixture": "fixture", } Handling Responses ~~~~~~~~~~~~~~~~~~ RESTCat responses is in JSON format. We may add add other formats later. Your client code should pay attention to the HTTP response code first. "200" is the "OK" response in HTTP so this indicates that all went well. If you receive something besides a 200 then something went wrong. In most cases, the body will contain additional information about the error. Here is a list of potential responses and their meaning: ========= ============================================================ RESPONSE MEANING ========= ============================================================ 200 OK 400 Bad Request: Error in your request 401 Not Authorized: Invalid credentials 403 Forbidden 405 Method not Allowed 404 Resource Not Found 409 Resource Conflict: i.e the user or transaction already exists 410 Gone: The resource no longer exists 500 Internal Server Error 501 Method not implemented ========= ============================================================ If the result is 200, then the body of the server response will contain the requested data or other information about the successful execution of the call. If the result was an error your JSON file will contain at least 2 elements; 'code', indicating the HTTP code, and 'message', containing additional information about the error. Here are a couple examples: :: "{code: '400', message: 'You must supply a grantor, grantee, and sec_level'}" "{code: '404', message: 'Grantor user Does Not Exist.', exists: false}" "{code: '401', message: 'Unauthorized'}" "{code: '200', message: 'User mickeymouse created.'}" "{code: '409', message: 'Duplicate/Conflict'}" Accounts ~~~~~~~~ These methods are responsible for creating users, associating users, and querying user information. Test Login ~~~~~~~~~~ Test that your HTTP auth login credentials were accepted. ================== ============================================================ URL [HOST]/accounts/testlogin/ ================== ============================================================ HTTP Method GET Credentials HTTP Auth username and password Requires None Accepts None Returns on Success HTTP 200 A message that you were logged in Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: curl -u http://127.0.0.1:8000/accounts/testlogin -o out.json Account Create ~~~~~~~~~~~~~~ You must have the accounts.can_create_users permission to execute this API method. Also note that a social graph is automatically created between a user and herself and between the user and her creator when a user account is created with the API. You must always supply a unique username and email. ================== ============================================================ URL [HOST]/accounts/create/ ================== ============================================================ HTTP Method POST Credentials HTTP Auth username and password Requires: username, email, first_name, last_name, password, pin, gender, height_in, birthdate Accepts complaint_title, complaint_detail, phone_number, mobile_phone_number, fax_number, organization, twitter, allergies, medications, conditions, procedures, primary_insurance_or_payer, secondary_insurance_or_payer, step_per_day_goal, weight_goal Returns on Success HTTP 200 and Response string (JSON by default) Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: curl -u user:pass http://127.0.0.1:8000/accounts/create/ -X POST -d "username=mickeymouse&password=bar&first_name=alan&last_name=viars&email=alan@foo.com&height_in=69&weight_goal=150&gender=male&pin=1234&birthdate=1980-12-20" -o out.json Account Update ~~~~~~~~~~~~~~ This works just like create except it updates the user except for the password. You must have the accounts.can_create_users permission to execute this API method. ================== ============================================================ URL [HOST]api/accounts/update/ ================== ============================================================ HTTP Method POST Credentials HTTP Auth username and password Requires: username, email, first_name, last_name, pin, gender, height_in, birthdate Accepts complaint_title, complaint_detail, phone_number, mobile_phone_number, fax_number, organization, twitter, allergies, medications, conditions, procedures, primary_insurance_or_payer, secondary_insurance_or_payer, step_per_day_goal, weight_goal Returns on Success HTTP 200 and Response string (JSON by default) Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: curl -u user:pass http://127.0.0.1:8000/accounts/update/ -X POST -d "username=mickeymouse&first_name=alan&last_name=viars&email=alan@foo.com&height_in=69&weight_goal=150&gender=male&pin=1234&birthdate=1980-12-20" -o out.json Check if a user exists ~~~~~~~~~~~~~~~~~~~~~~ ================== ============================================================ URL [HOST]api/accounts/checkexists/[email]/ ================== ============================================================ HTTP Method GET Credentials HTTP Auth username and password Requires None Accepts None Returns on Success HTTP 200 and the user's account information in the body Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: https://127.0.0.1/api/accounts/checkexists/alan@foo.com/ Get a list of friends' email addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ================== ============================================================ URL [HOST]api/accounts/emaillist/[email]/ ================== ============================================================ HTTP Method GET Credentials HTTP Auth username and password Requires None Accepts None Returns on Success HTTP 200 and a list of a user's associations Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: https://127.0.0.1/api/accounts/emaillist/alan@foo.com/ Get a User's Profile ~~~~~~~~~~~~~~~~~~~~ ================== ============================================================ URL [HOST]api/accounts/userprofile/[email]/ ================== ============================================================ HTTP Method GET Credentials HTTP Auth username and password Requires None Accepts None Returns on Success HTTP 200 and a user's profile Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: https://127.0.0.1/api/accounts/userprofile/alan@foo.com/ Social Graph Create ~~~~~~~~~~~~~~~~~~~ You can always grant others access to your information. In order to create other social graphs, you will require the accounts.can_create_any_social_graph permission. A social graph is automatically created between a user and herself and between a user and the creator when a user account is created. Grantor and grantee must be valid email address from valid users. ================== ============================================================ URL [HOST]/accounts/create/ ================== ============================================================ HTTP Method POST Credentials HTTP Auth username and password Requires: grantor, grantee, security_level Accepts: Returns on Success HTTP 200 and Response string (JSON by default) Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ ================= ============================================================ Security Level Description ================= ============================================================ 1 Highest (Default) 2 Medium 3 Lowest ================= ============================================================ Example: :: curl -u user:password -X POST -d "grantor=alan@foo.com&grantee=rebecca@goo.com&security_level=1" http://127.0.0.1:8000/accounts/socialgraph/create/ -o out.json Generic Transactions ~~~~~~~~~~~~~~~~~~~~ Read a Transaction ~~~~~~~~~~~~~~~~~~ ================== ============================================================ URL [HOST]api/transaction/read/[id]/ ================== ============================================================ HTTP Method GET Credentials HTTP Auth username and password Requires id (A unique id for the transaction being requested) Accepts None Returns on Success HTTP 200 and the requested transaction Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: curl -u user:pass http://127.0.0.1/api/transaction/read/a1f4f4f8-d5e9-4a55-a57e-a22eefb7a3a5/ Create a Transaction ~~~~~~~~~~~~~~~~~~~~ This is key method for creating transactions. probably the most important ================== ============================================================ URL [HOST]/transaction/create/ ================== ============================================================ HTTP Method POST Credentials HTTP Auth username and password Requires See Transaction Model Accepts See Transaction Model Returns on Success HTTP 200 and the newly created transaction Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: curl -u testuser:password -X POST -d "tx_dt=20100920:175047z&ev_tz=-5&texti=bp110/75p61&rcvr=ahaapp@aha.org&sec=3&sndr=ysobande@gmail.com&ev_dt=20100919:121212z&tx_tz=-5&ttype=omhe&subj=ysobande@gmail.com&id=c5ea845e-a99e-4e89-974a-8203fc9f6fc3" http://restcat1.wellrbox.com:8000/transaction/create/ -o out.json Create a Transaction with a File Attachment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to upload a file, with your transaction, do it like this. :: curl -u alan:pass --form file=@pycurl.txt --form "id=c5ea845e-a99e-4e89-974a-8203fc9f6fc" --form "tx_dt=20100920:175047z" --form "tx_tz=-5 --form "ev_dt=O20100920:175047" --form "ev_tz=-5" --form "sndr=foo@bar.com" --form "rcvr=foo@bar.com" --form "subj=foo@bar.com" --form "ttype=pdf" --form "filename=my.pdf" http://127.0.0.1:8000/transaction/create/ -o out.html curl -u alan:pass --form file=@pycurl.txt --form "id=c5ea845e-a99e-4e89-974a-8203fc9f6fc" --form "tx_dt=20100920:175047z" --form "tx_tz=-5 --form "ev_dt=O20100920:175047" --form "ev_tz=-5" --form "sndr=foo@bar.com" --form "rcvr=foo@bar.com" --form "subj=foo@bar.com" --form "ttype=pdf" --form "filename=my.pdf" http://127.0.0.1:8000/transaction/create/ -o out.html tx_tz=-4 ev_tz=-5 texti=bp110/75p61 sndr=ysobande@gmail.com rcvr=ahaapp@aha.org subj=ysobande@gmail.com sec=3 m& v_dt=20100919:121212z tx_tz=-5 ttype=omhe 3 The resulting transaction will contain a `uri` item pointing to the file you uploaded. Your server settings will determine where and how your files are stored. RESTCat supports local and Amazon AWS S3 storage. Find Transactions (Search) ~~~~~~~~~~~~~~~~~~~~~~~~~~ This method allows you to pass in a query string and return the query set if it exists. ================== ============================================================ URL [HOST]api/transaction/find[query_string] ================== ============================================================ HTTP Method GET Credentials HTTP Auth username and password Requires A query string Accepts None Returns on Success HTTP 200 and the query result Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: curl -u user:pass http://127.0.0.1/api/transaction/find?subj=alan@foo.com&sndr=rebecca@goo.com OMHE Transactions ~~~~~~~~~~~~~~~~~ These API methods are provided as convenience functions when working with OMHE formatted data. You could use the methods described above, but you may find the methods described below eaiser. Find OMHE Reading for a Particular User ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Get all the measurements for a particular metric for a particular user. ================== ============================================================ URL [HOST]api/find/omhe/[omhe_command]/[sub]/ ================== ============================================================ HTTP Method GET Credentials HTTP Auth username and password Requires An OMHE command and a subject's email Accepts None Returns on Success HTTP 200 and the query result Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: curl -u ysobande:password http://127.0.0.1/api/omhe/find/bp/ysobande@gmail.com/ -o out.json url(r'^api/omhe/find/(?P[^/]+)/(?P[^/]+)/$', find_omhe_for_user, name='find_omhe_for_user'), Find OMHE reading for a particular user for only the past 30 days ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The same as above but just return the last 30 days. ================== ============================================================ URL [HOST]api/find/omhe30/[omhe_command]/[sub]/ ================== ============================================================ HTTP Method GET Credentials HTTP Auth username and password Requires An OMHE command and a subject's email Accepts None Returns on Success HTTP 200 and the query result Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: curl -u ysobande:password http://127.0.0.1/api/omhe/find/bp/ysobande@gmail.com/ -o out.json Compare Two User's OMHE Measurements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This method returns 2 users' measurements (so they may be compared). ================== ============================================================ URL [HOST]api/omhe/compare/[omhe_command]/[subj1]/[subj2]/ ================== ============================================================ HTTP Method GET Credentials HTTP Auth username and password Requires An OMHE command, subject 1's email, and subject 2's email Accepts None Returns on Success HTTP 200 and the query result Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: curl -u user:pass http://127.0.0.1/api/omhe/compare/spd/alan@foo.com/chris@bar.com/ Population: ~~~~~~~~~~~ These commands support population-level query and aggregation of sample data. Find OMHE reading for a Population ---------------------------------- Get all the data from everyone (you are allowed to see) for a particular measurement. ================== ============================================================ URL [HOST]api/population/omhe/find/[omhe_command]/ ================== ============================================================ HTTP Method GET Credentials HTTP Auth username and password Requires An OMHE command. (e.g. bp, wt, etc) Accepts None Returns on Success HTTP 200 and the query result Returns on Fail Non-200 HTTP response and message about the error ================== ============================================================ Example: :: curl -u user:password http://127.0.0.1/api/population/omhe/find/bp/