API: Postman Installation Cookbook
- Legal Notice
-
The information provided herein is »AS IS«. The information contained in this document is subject to change without notice. Better, d.o.o. (hereinafter: Better) gives no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Better shall not be liable for any errors contained herein, or for incidental or consequential damages in connection with the furnishing, performance or use of this material.
(c) Better - Reproduction, adaptation or translation without a prior written permission is prohibited, except as allowed under the copyright laws.
- Conventions
-
This document uses the following symbolic conventions:
Courier textCourier text indicates filenames and their contents, computer input and output, program code, etc. For example: “To see the status of server, type
ps -ef | grep java.”Italicized text
Italic text indicates document titles, parameters, emphasized text and replaceable text.
bold text
Bold text indicates emphasized text.
<angle brackets>
Angle brackets indicate generic variable names that must be substituted by real values or strings.
- We welcome your comments
-
Your feedback on the information in this guide is important to us. Please send your comments about this guide to make it even clearer and more accurate.
- Browser support
-
Our products work with all the latest major browser releases and do not require any special additions, extensions or previous setup. We discourage using Internet Explorer at all.
We do support:
-
Edge 17+,
-
Chrome 60+,
-
Firefox 56+,
-
Safari 11+,
-
Opera 50+.
-
About
Postman serves as a ideal API client, easy to configure and send the requests towards different API endpoints for testing or learning purposes.
Glossary
- Better Platform
-
Better Platform is a big-data, high-performance solution designed to store, manage, query, retrieve and exchange structured electronic health record data based on the latest release of openEHR specifications. All clinical information is stored in vendor-independent archetypes and templates, allowing standard data entry and retrieval with terminology based validation.
See https://platform.better.care - EHR Server
-
EHR Server is the core part of Better Platform, hosting services and exposing the API.
- Sandbox
-
Sandbox is a cloud hosted Better Platform installation. Here you can test most of the API. With a user account you can use and test full Better Platform potential in your own sandbox.
See https://www.better.care/try-sandbox - Postman
-
Application for client side API testing and developing.
See https://www.getpostman.com - JSON
-
JavaScript Object Notation - a lightweight format for storing and transporting data
- HTTP
-
Hyper Text Transfer Protocol - an application protocol for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data communication for the World Wide Web, where hypertext documents include hyperlinks to other resources that the user can easily access, for example by a mouse click or by tapping the screen in a web browser.
- REST
-
Representational State Transfer - a software architectural style that defines a set of constraints to be used for creating Web services.
- XML
-
Extensible Markup Language - a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable
- SOAP
-
Simple Object Access Protocol - XML-based messaging protocol for exchanging information among computers
- EHR
- EHR ID
-
Single EHR unique identifier
- Composition
-
Digital document containing clinical data.
- AQL
Related information
Cookbooks are a series of user oriented step by step guides on how to get things done with Better Platform.
Consult the following documents to get familiar with the Better Platform in relation to EHR Server API:
-
EHR Server: Developer guide
-
Demographics Cookbook
-
EHR Server API Cookbook
Installation
Download Postman installation files and follow the instructions: https://www.postman.com/downloads
Once the installation is finished, start Postman.
Workspace setup
We recommend creating a separate workspace for API testing.
Step 1: Click on My Workspace dropdown
Step 2: Click on Create new button
Step 3: Configure new space Name your workspace and mark it as Personal, for local work. Then click Create workspace.
Follow this link for more details and instructions:
https://www.getpostman.com/docs/v6/postman/workspaces/managing_workspaces
Import environment settings
Step 4: Setup the environment
Step 5: Import the variables
Select the file EhrScape.postman_environment.json and confirm the import.
New entry named EhrScape will be displayed.
Now close the window.
Two environment variables are predefined:
| variable name | description |
|---|---|
baseUrl |
URL where the EHR Server API is accessible |
templateId |
name of the template to be used for composition creation |
Other variables such as ehrId and compositionId will automatically be added as you test different API calls.
Step 6: Select the active environment
From the environment dropdown select the EhrScape environment.
Your environment is now ready!
Follow this link for more details and instructions:
https://www.getpostman.com/docs/v6/postman/environments_and_globals/manage_environments
Local Better Platform installation
If you have a local Better Platform installation, ask your administrator for the URL on which it is available.
It might be in a form of hostname (e.g. https://platform.mydomain.org or https://mydomain.org/platform or http://mydomain.org:8080) or IP numbers (e.g. https://192.168.0.1:8080).
Append /rest/v1 string to the hostname (if it is missing) - this is where you access the EHR Server API.
Make sure the URL does not end with a forward slash and the schema (http or https) matches the server settings.
Now you need to update the environment variable baseUrl with this value.
If you are using a different template for your testing, update also templateId variable.
Follow this link for more details and instructions:
https://www.getpostman.com/docs/v6/postman/environments_and_globals/manage_environments
Import the collection
The list of API requests is stored in a collection that you need to import in your current workspace.
Step 7: Click on the Import button
On tab Import file select the file EHR Server API.postman_collection.json and confirm the import.
New collection named EHR Server API is diplayed:
Authorization configuration
This section gives instructions on how to use Sandbox credentials. If you have a local Better Platform installation, ask your administrator to provide you with the appropriate credentials and use those.
Get Sandbox credentials
Visit the https://www.better.care/try-sandbox site and request an access account, which gives you a private sandbox with read/write permissions.
Setup the Postman authorization credentials
Step 8: Click on the collection “…” button and select Edit
Step 9: Go to Authorization tab and enter your credentials
When you are finished entering your credentials, click Update and you are ready to go!
Test the setup
To test your setup, open the collection section for endpoint Templates and select the Get template list request.
Click the Send button on the right and wait for the response.
Response
If the response is similar to the one on the image above, you are good to go!
If the response is in HTML form describing an error, or it says Could not get any response follow the eventual instructions presented in the HTML or check the baseUrl environment variable value.
Status
Check the Status code:
| status code | description |
|---|---|
200 |
Everything is ok, data section contains a list of installed templates. |
204 |
Everthing is ok, but no templates are installed on EHR Server. |
401 |
There is a problem with authorisation. Check your credentials settings. |
404 |
EHR Server not responding. Check if the EHR Server is running and if your |