Symptom Checker API v1.2 Documentation

Transcription

1 Symptom Checker API v1.2 Documentation

2 07/06/16 Self Care Decisions Symptom Checker API 2 Symptom Checker API v1.2 Overview... 3 Supplemental Resources... 4 Sample Web Application and User Story... 4 Interaction Model... 5 URL Formation... 6 Version Code... 6 Language Code... 6 Authentication... 6 Version Code... 6 Cross Site Scripting with JSONP... 7 Symptom Checker... 8 Index... 8 Symptom Checker Topic Special Topic Image Topic First Aid Index Dosage Tables Index Dosage Table Topic Parent Advice Messages Index Parent Advice Message Supplemental Topics Index... 23

3 07/06/16 Self Care Decisions Symptom Checker API 3 Symptom Checker API v1.2 Overview The Symptom Checker API is a restful web service allowing licensed clients to interface with Self Care Decision s Symptom Checker content. Self Care Decisions currently offers 132 Pediatric and 108 Adult Symptom Checker care guides, as well as 213 additional Images, 55 First Aid Topics and 25 Drug Dosage Tables (7 pediatric; 18 adult). These topics are organized into Symptom Checker, First Aid and Dosage Table indices. The Symptom Checker API returns a JSON response for each index and each topic. An additional content set containing 145 Parent Advice Messages is also available. These topics offer advice for pediatric behavior, eating and wellness questions. Nine supplemental information topics with user instructions, information about the authors, reviewers, copyright and disclaimer are also available. Symptom Checker First Aid Index Adult Index Pediatric Index First Aid Topic Symptom Checker Topic Symptom Checker Topic Special Topic Symptom Checker API Dosage Table Index Pediatric Dosage Table Topic Adult Dosage Table Topic Parent Advice Message Index Parent Advice Topic Supplemental Information Supplemental Topic

4 07/06/16 Self Care Decisions Symptom Checker API 4 Supplemental Resources Sample Web Application and User Story This documentation is supplemented with a sample web application and a user story. These resources are meant to help developers understand the organization of our content and begin developing their applications. Developer Portal Once you have licensed the Symptom Checker API, you will be supplied a link and credentials to access your developer portal. Here you will manage your API keys and have access to the latest API documentation and supplemental API resources. You will also find an API request formation tool allowing you to see properly formed API requests and their response values. Sample Web Application Found on the Resources page of the Developer Portal, this sample web application is a client side implementation of the content made available by the Symptom Checker API. It uses the jquery javascript library to render HTML from the Symptom Checker API response values. Developers are encouraged to use the sample web application source as a reference in their implementation. User Story In addition to the sample web application, a user story is also provided on the Resources page of the Developer Portal. This user story contains a narrative of the typical interaction between a user and the Symptom Checker API and is supplemented with screenshots from the sample web application.

5 07/06/16 Self Care Decisions Symptom Checker API 5 Interaction Model As shown in the Symptom Checker API Overview diagram, the Symptom Checker API responds to calls for the Adult and Pediatric Symptom Checker indices as well as 4 supplemental indices. Interaction between the client and the server should typically begin with a request for the desired index. In the case of a Symptom Checker index call, an age parameter of adult or peds (pediatric) is required. The client requests the index with the appropriate parameter from the server and the server returns a JSON response. The client renders this response into a user interface and prompts the user to make a selection. When a topic is selected, this process is repeated. The client requests the topic with the selected topic s ID parameter and the server returns a JSON response containing all of the data associated with that topic. The client renders this response into a user interface displaying the topic information to the user. For complete documentation of the Interaction Model please refer to the User Story document provided along with this documentation. Client Server GET topictable with AGE RETURN titles object GET topic with ID RETURN topic object

6 07/06/16 Self Care Decisions Symptom Checker API 6 URL Formation Development and Production Environments Development environment address (requires authentication): Production environment address (requires authentication): The Symptom Checker API can be accessed at two different addresses. There is a development environment that should be used during application development, and a production environment that should be used in live applications. Both the development and the production environments offer the complete Symptom Checker API. The development environment is a virtual server that hosts both web and SQL servers and the production environment is redundant, separate web and SQL servers using RRDNS and DNS failover. Version Code Example URL: The path for Symptom Checker API calls must include a version code. The version code in the example is 1.2. In the URL above, you will see that the version code follows json/ in the URL, and will precede any parameters for a requested file. Any change made to the organization of the Symptom Checker API return values will be made on a subsequent version. When new versions are available, developers will be notified and provided updated documentation so that they can begin developing on the new version. When a new version is released, the previous version will remain available for at least one year from the release of the new version. Language Code Example URL: The path for Symptom Checker API requests must include a language code. The language code in the example is en. In the URL above, you will see that the language code follows the version code in the URL. The English language code is en and the Spanish language code is es. Please be sure to use an appropriate language code based on your license. Authentication Example URL: The Symptom Checker API uses keyed-hash message authentication code (HMAC) for authentication and identification. A public key, the URL for the requested resource and the current Unix timestamp are to be combined in that order, separated by " " (vertical bar) characters to form the HMAC message. An application specific private key will be provided to

7 07/06/16 Self Care Decisions Symptom Checker API 7 be used as the HMAC key. HMAC construction using SHA-256 encoding should be performed on the message and the private key in order to calculate a HMAC token. The HMAC token should then be encoded using base 64 encoding. This token should be included with every API request, along with parameters specifying the public key and a timestamp for the request. Requests are valid for 300 seconds, or 5 minutes from formation. Example HMAC Message for adult topic table: abc json/1.2/en/topictable/adult In this example, the public key is abc, the URL for the requested resource is json/1.2/en/topictable/adult and the timestamp is Note that the url for the requested resource omits the portion of the path, and also any parameters. To see a working example, please review the file provided in the sample web application at Note that private keys must be kept private. For the purposes of the sample web application, the private key is kept in plain text in client side code. This should not be the case in production applications. If a private key is leaked, a new key will have to be issued and the application will have to be updated immediately. The old key will need to be revoked in order to prevent API misuse. Private keys can be found in the developer portal. Cross Site Scripting with JSONP Example URL: The Symptom Checker API utilizes JSONP to accommodate cross-site scripting. JSONP stands for JSON with padding and is a communication technique that involves wrapping a JSON object in a JavaScript callback function in order to circumvent the same origin policy enforced by many modern web browsers. You can request a JSONP response from the Symptom Checker API by appending?callback=? to your request.

8 07/06/16 Self Care Decisions Symptom Checker API 8 Symptom Checker Index Symptom Checker Index API Call Sample URL: BodyArea=BodyArea&BodyRegion=BodyRegion&BodyPart=BodyPart Possible Parameters: AGE (required), BodyArea, BodyRegion, BodyPart Parameter Value Description AGE adult, peds Specifies the age range for the index data that should be returned BodyArea e.g. Arm%20or%20Ha nd String from bodyarea Specifies a filter for a particular Body Area. Body Area values can be found here - en/bodyarea BodyRegion e.g. Arm String from bodyregions Specifies a filter for a particular Body Region. Body Region values can be found here - en/bodyregion BodyPart e.g. Wrist String from bodyparts Specifies a filter for a particular Body Part. Body Part values can be found here - en/bodypart The index API call is used to get the full index for the specified age range. The response is a simple JSON string which contains an array of titles objects. Each titles object has the following keys: id: INT, primary key for topic title: STRING, title for topic

9 07/06/16 Self Care Decisions Symptom Checker API 9 specialtopic: BOOL, true for supplemental information topics and false for regular symptom checker topics pediatric: BOOL, true for pediatric, false for not pediatric (adult) gender: STRING, M for male, F for female, or B for both. A supplemental table containing possible values can be found here: bodyareas: ARRAY of STRING values, specifying body area topic is related to. Possible values are: Baby Symptoms, Head or Brain, Eye, Ear, Nose, Mouth or Teeth, Neck or Back, Arm or Hand, Chest, Abdomen, Pregnancy, Genitals or Urinary, Bottom, Leg or Foot, Skin, Other Symptoms. A supplemental table of possible values can be requested here: keywords: ARRAY of STRING values, specifying a keyword or keyword phrase associated with topic. "titles": [ "id": "7", "title": "Bee or Yellow Jacket Sting ", "specialtopic": false, "pediatric": "true", "gender": "B", "bodyareas": [ "Skin", "keywords": [ "BEE" BodyArea1 This endpoint is supplemental to the /bodyareas endpoint. It returns an array of objects, rather than an array of strings. These objects describe the body area in more detail. BodyArea1 API Call Sample URL:

10 07/06/16 Self Care Decisions Symptom Checker API 10 bodyareas: ARRAY of bodyarea objects id: STRING, id for bodyarea. Is usually the title of the area in the default language (English) title: STRING, title for bodyarea gender: STRING, "M, F or B for male, female or both. age: STRING, adult, child, both describing the age range that the body area applies to. order: INT, range of specifying an order for body area listings. It is based off of ten so that there is room to grow. "bodyareas": [ "id": "Baby Symptoms", "title": "Baby Symptoms", "age": "child", gender : B, "order": 10, "id": "Head or Brain", "title": "Head or Brain", "age": "both", gender : B, "order": 20,

11 07/06/16 Self Care Decisions Symptom Checker API 11 Symptom Checker Topic The primary goals of the symptom checker topic are to match a user to a description of his/her symptoms and to identify what level of care (dispositions:) is recommended to treat those symptoms. This is accomplished by offering a definition (definition: detail:) and any related topics (alternatetopics: alternatetopic) to the user. If the user feels his/her symptoms match the definition offered in a symptom checker topic, then the user progresses to a decision tree to assess what level of care is recommended. The user is asked to read through a list of triage statements and identify the first statement that matches his/her symptom scenario. The triage statements are organized into sections (dispositions:) which prompt the user to take a particular action. These sections should be organized from most severe (dispositions: level: 100) to least severe (dispositions: level: 10). When the user identifies a triage statement (dispositions: detail: text:) that describes his/her symptom scenario, he/she is instructed to take the appropriate action for the disposition level for that statement (dispositions: text:). If the user s symptom is matched to a disposition level 65 or lower (any non-urgent disposition), the user should be directed to read through the care advice (advice:). Each topic also offers Causes and Additional health information (background:) and may offer Images (images:) relevant to the topic. Symptom Checker Topic API Call Sample URL: Possible Parameters: ID (required) Parameter Value Description ID Integer > 0 The primary key for the requested topic The Symptom Checker Topic API call is used to get the data for any Symptom Checker Topic. The response is a complex JSON string which contains a topic object. The topic object contains the following keys: id: INT, primary key for topic title: STRING, title for topic pediatric: BOOL, true for pediatric, false for non-pediatric (adult)

12 07/06/16 Self Care Decisions Symptom Checker API 12 gender: STRING, M for male, F for female, or B for both. A supplemental table containing possible values can be found here: disclaimer: STRING, containing text for disclaimer. copyright: STRING, containing text for copyright. definition: o header: STRING, text asking if this is your symptom or your child s symptom based upon age for topic. o detail: ARRAY of STRING values with text describing symptom alternatetopics: optional o header: STRING, text introducing related topics o alternatetopic: ARRAY of related topics id: INTEGER, specifying primary key for related topic title: STRING, specifying the title for related topic images: ARRAY, supplemental image object, optional o id: STRING, primary key for image topic o thumbref: STRING, file name of thumbnail for image topic o top4: BOOL, flag specifying true if the image is one of the top 4 images that should be shown for the topic, and false if it is not. o title: STRING, specifying the title for the image topic dispositions: ARRAY, disposition objects describing the level of care recommended for an array of triage statements (questions:) pertaining to the symptom. The level and description values are correlated, and they have the following possible values: 100 Call 911 Now, 90 Call Your Doctor Now or Go to ER, 89 Call Your Dentist or Doctor Now, 85 Call Poison Center Now, 65 Call Your Doctor Within 24 Hours, 64 Call Your Dentist Within 24 Hours, 20 Call Your Doctor During Weekday Office Hours, 19 Call Your Dentist During Office Hours, 10 Self Care at Home. A supplemental table with the level and text values for all possible values is available here: o level: INT, key for the level of care needed. o description: STRING, describing the level of care recommended for an array of statements o questions: ARRAY, triage statements id: INT, primary key for statement sequence: INT, specifying the order that the statement should display within the disposition array telemedicine: STRING, describing what level of telemedicine might be appropriate if the triage statement is a match for the user s symptom scenario. Possible values are na for not appropriate, audio for audio only (telephone), audio+image for audio with store/forward or video image (asynchronous telemedicine service), audio+video for audio-

13 07/06/16 Self Care Decisions Symptom Checker API 13 video/webcam, audio+data for audio-video enhanced, potentially with a data feed from adjunctive medical devices. A supplemental table with possible values can be found here: edicine text: STRING, the text for the question statement urgentcare: BOOLEAN, True indicates that an Urgent Care option would be safe and appropriate. False indicates that an Urgent Care is not indicated for the symptom scenario described by that triage question. firstaidid: INT, optional. The primary key for any first aid advice associated with the triage statement (questions:). firstaidtitle: STRING, optional. Specifying the title for any first aid advice associated with the triage statement. advice: o title: STRING, the title for the care advice topic o text: STRING, HTML for the body of the care advice topic o footer: STRING, the footer for the care advice topic background: STRING, HTML offering causes and additional health information related to the topic "topic": "id": "7", "title": "Bee Sting", "pediatric": true, "gender": "B", "disclaimer": "Disclaimer: This information is not intended...", "copyright": "Copyright ", "definition": "header": "Is this your child's symptom?", "detail": [ "Stung by a honeybee, bumblebee, hornet, wasp, or yellow jacket", "alternatetopics": "header": "If NOT, try one of these:", "alternatetopic": [ "id": "58", "title": "Insect Bite"

14 07/06/16 Self Care Decisions Symptom Checker API 14, "firstaid": [ "description": "<ul><li>for Anaphylaxis - Epinephrine</li></ul>", "text": "<p><strong>first Aid for Anaphylaxis - Epinephrine</strong></p>...", "images": [ "id": "30", "title": "Bee Sting of Left Hand", "thumbref": "beesting3_x124.jpg", "top4": true, "dispositions": [ "level": "100", "text": "Call 911 Now", "questions": [ "id": "10382", "sequence": "1", "telemedicine": "na", "text": "Past severe allergic reaction to bee stings (not just hives) and stung less than 2 hours ago", "firstaidid": "503", "firstaidtitle": "Anaphylaxis - Child", "urgentcare": false, "advice": "title": "Care Advice for Bee or Yellow Jacket Sting", "text": "<p><strong></strong></p><ol><li><strong>what You Should Know About Bee Stings:</strong><ul><li>...", "background": "<p><strong>cause of Bee Sting Reactions</strong></p><ul><li>...",

15 07/06/16 Self Care Decisions Symptom Checker API 15 "bodyareas": [ "Skin" Special Topic The Special Topic is a supplementary topic which is included in the Pediatric Symptom Checker Index. These topics offer supplemental information, but do not fit the regular Symptom based triage model. They are much simpler. There are currently 6 of these topics. Special Topic API Call Sample URL: Possible Parameters: id (required) Parameter Value Description ID Integer The primary key for the requested topic The Special Topic API call is used to get the data for any Special Topic. The response is a simple JSON string which contains a specialtopic object. The specialtopic object contains the following keys: id: INT, primary key for the special topic title: STRING, text for the title of the topic text: STRING, HTML for the body of the topic author: STRING, text with the author of the topic copyright: STRING, text with the copyright information of the topic "specialtopic": "id": "992", "title": "Emergency Symptoms Not To Miss", "text": "text", "author": "author", "copyright": "copyright"

16 07/06/16 Self Care Decisions Symptom Checker API 16 Image Topic The Image Topic is a supplementary topic that features an image and text. Image topics may be accessed from a symptom checker topic or the first aid index. Image Topic API Call Sample URL: Possible Parameters: id (required) Parameter Value Description ID Integer The primary key for the requested topic The Image Topic API call is used to get the data for any Image Topic. The response is a simple JSON string which contains an image object. The image object contains the following keys: id: INT, primary key for the image topic thumbref: STRING, file name of thumbnail for image topic imageref: STRING, file name of full image for image topic title: STRING, text for the title of the image topic text: STRING, HTML for the body of the image topic source: STRING, text with the source of the image copyright: STRING, text with the copyright information of the image topic "image": "id": 30, "thumbref": "beesting3_x124.jpg", "imageref": "beesting3.jpg", "title": "Bee Sting of Left Hand", "text": "<p>moderate swelling of left hand, "source": "LMS Inc.", "copyright": "Copyright

17 07/06/16 Self Care Decisions Symptom Checker API 17 First Aid Index The First Aid Index makes the image topics that offer first aid advice accessible from an independent index. All of the first aid topics should be requested using the Image Topic API Call in the previous section of this document. It is suggested that the First Aid index should be displayed in two sections, Life-Threatening and All First Aid Topics. This allows users to quickly find First Aid advice for life-threatening conditions without having to browse the full index. The first aid topics are image topics and should be accessed via an image topic API call for the appropriate ID. First Aid Topic API Call Sample URL: No possible parameters. The response is a simple JSON string which contains an array of titles objects. Each titles object contains the following keys: id: INT, primary key for first aid topic (image topic) keywords: ARRAY of STRING values, specifying a keyword or keyword phrase associated with topic thumbref: STRING, url for the thumbnail image title: STRING, text for the title of the first aid topic lifethreatening: BOOL, true if the topic offers first aid advice for a life threatening condition, false if not. "titles": [ "id": "361", "keywords": [ "ELECTRIC", "thumbref": "fa_elecshock_x124.jpg", "title": "Electrical Shock Rescue", lifethreatening : true

18 07/06/16 Self Care Decisions Symptom Checker API 18 First Aid Topic The first aid topics are image topics and should be accessed via an image topic API call for the appropriate ID. First Aid Group API Call Both encounter and population-based licenses allow for the caching of the first aid content. The goal of this is to allow application developers to cache the first aid content so that users may have access to this content when they are experiencing limited connectivity. To accommodate this, the First Aid Group API Call is provided, allowing developers to request the First Aid Index, and all of the First Aid Image Topics simultaneously. First Aid Group API Call Sample URL: Possible Parameters: TIME (required) Parameter Value Description TIME Integer Unix time stamp in seconds for the previous request. The time parameter of 0 will return all of the first aid content and should be used on the initial cache. When the response has been cached, a Unix time stamp should be recorded. This time stamp should be used for the time parameter in the next request. The First Aid Group API Call will only respond with any indices or topics that have been updated since the Unix time indicated by the time parameter. The response is a complex JSON string which contains a titles object with an array of values and an image object with an array of values. titles: OBJECT containing titles ARRAY, an array of titles objects with an identical response to a first aid index API call (See example for schema. SCD acknowledges that the nesting of titles objects is unnecessary and will resolve this in the next major version release. Contact SCD if this poses any problems for you) image: ARRAY, an array of image objects with an identical response as an image topic API call "image":[, "titles":"titles":[

19 07/06/16 Self Care Decisions Symptom Checker API 19 Dosage Table Topics Index The Dosage Table Index makes Dosage Table Topics accessible from an independent index. There are currently 7 Pediatric and 18 Adult Dosage Table Topics available. Dosage Table Index API Call Sample URL: Parameter Value Description AGE adult, peds Specifies the age range for the index data that should be returned The response is a simple JSON string which contains an array of titles objects. Each titles object contains the following keys: id: INT, primary key for dosage table topic title: STRING, text for the title of the dosage table topic "titles": [ "id": "299", "title": "Acetaminophen (Tylenol)"

20 07/06/16 Self Care Decisions Symptom Checker API 20 Dosage Table Topic The Dosage Table Topic is a supplementary topic that features an HTML table showing dosage information for common over-the-counter medications. Dosage table topics may be accessed from the Dosage Table Index. Dosage Table Topic API Call Sample URL: Possible Parameters: id (required) Parameter Value Description ID Integer The primary key for the requested topic The Dosage Table Topic API call is used to get the data for any Dosage Table Topic. The response is a simple JSON string which contains a dosagetable object. The dosagetable object contains the following keys: id: INT, primary key for the dosage table topic title: STRING, text for the title of the dosage table topic text: STRING, HTML for the body of the dosage table topic author: STRING, text with the author of the dosage table topic copyright: STRING, text with the copyright information of the dosage table topic "id": 299, "title": "Acetaminophen (Tylenol) Dose Table", "text": "<table border=\"1\" cellpadding=\"6\" width=\"100%\"><tr> ", "author": "Barton D. Schmitt, M.D.", "copyright": "Copyright Barton D. Schmitt, M.D."

21 07/06/16 Self Care Decisions Symptom Checker API 21 Parent Advice Messages Index The Parent Advice Message Index makes the Parent Advice Messages accessible. It is recommended that the Parent Advice Message Index be organized by category. Parent Advice Message Index API Call Sample URL: No possible parameters. The response is a simple JSON string which contains an array of titles objects. Each titles object contains the following keys: id: INT, primary key for parent advice message category: STRING, text specifying the category which is most appropriate for the parent advice message. Possible values are: "Behavior Problems: Others", "Discipline Problems", "Eating Problems", "Family Issues", "Injury Prevention", "School Problems", "Sleep Problems", "Staying Healthy (Wellness)", "Teenagers", "Toilet Training and Bedwetting". A supplemental table with possible values is available here: system: STRING, provides optional identification of the topic to a body system. A supplemental table with possible values is available here: title: STRING, text with the title for the parent advice message keywords: ARRAY of STRING values, text with any keywords or keyword phrases associated with the topic. "titles": [ "id": "22", "category": "Injury Prevention", "system": "Respiratory System", "title": "Drowning: Prevention", "keywords": [ "BATHTUB"

22 07/06/16 Self Care Decisions Symptom Checker API 22 Parent Advice Message A Parent Advice Message is a supplementary topic that provides advice for common pediatric behavior, eating and wellness concerns. The Parent Advice Message is accessed via the Parent Advice Message Index. Parent Advice Message API Call Sample URL: Possible Parameters: id (required) Parameter Value Description id Integer The primary key for the requested topic The Parent Advice Message API call is used to get the data for any Parent Advice Message. The response is a simple JSON string which contains a parentadvice object. The parentadvice object contains the following keys: id: INT, primary key for the parent advice message category: STRING, text specifying the category of behavior or concern in which the parent advice message best fits. A supplemental table with possible values is available here: system: STRING, provides optional identification of the topic to a body system. A supplemental table with possible values is available here: title: STRING, text for the title of the parent advice message text: STRING, HTML for the body of the parent advice message copyright: STRING, text with the copyright information of the parent advice message "parentadvice": "id": "22", "category": "Injury Prevention", "system": "Respiratory System", "title": "Drowning: Prevention", "text": " <p>drowning usually occurs in private swimming pools ", "copyright": " Copyright Barton Schmitt, M.D."

23 07/06/16 Self Care Decisions Symptom Checker API 23 Supplemental Topics Index The Symptom Checker API also includes supplemental topics with information regarding the content set. The supplemental topic table contains 3 informational topics regarding the use of the symptom checker, titled: Introduction, Instructions, and When To Call. It also contains Author and Reviewer information for both the adult and the pediatric content sets, copyright and disclaimer topics. These are all special topics and should be accessed via a special topic API call for the appropriate ID. Supplemental Topic Index API Call Sample URL: No possible parameters. The response is a simple JSON string which contains an array of titles objects. Each titles object contains the following keys: id: INT, primary key for special topic title: STRING, text for the title of the special topic "titles": [ "id":"294, "title":"introduction"