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.
The following sections outline users, trust relationships, creating transactions, and querying results.
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. |
| 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. |
| 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 |
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
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",
}
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'}"
These methods are responsible for creating users, associating users, and querying user information.
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
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
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
| 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/
| 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/
| 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/
| 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/
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
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.
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
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.
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<omhe>[^/]+)/(?P<subj>[^/]+)/$’, find_omhe_for_user, name=’find_omhe_for_user’),
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
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/
These commands support population-level query and aggregation of sample data.
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/
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.
Example: