Technical Documentation

You can follow 5 steps to begin development of an application with the Medhost API portal.

Step 1: Sign up

User onboarding

To use Medhost API portal you must register an account.

Account registration requires:

  • Active email address
  • Unique username
  • Password

To register:

  1. Access Medhost API portal
  2. Click Signup or register for an account
  3. Enter your personal information, including an active email address
  4. Accept the terms of use
  5. If you are the Organization Administrator, click Next Step to enter your organization name from the acceptance screen
    1. Create a title  
    2. Enter description
  6. Click Register Now
  7. Verify the registration by clicking the link in the invitation to join email from the Medhost Developer Network

NOTE: The organization name is editable after you accept registration.

User management

Once you complete the signup process, you can invite users to your organization using any valid email address.

Click Organization to view:

  • Users in your organization 
  • Role
  • Status - enabled or disabled

Click Invitations to:

  • Invite new users
  • View users
  • Revoke user privileges

Step 2: Add an application

Application management

You can create your applications on the Medhost platform with the available application program interfaces (APIs). The account plan displays only the Bronze plan.

Click Applications to:

  • Add
  • View
  • Edit
  • Delete 

You need to know:

  • Type of platform - Android, iOS, or hybrid
  • API - or group of APIs you want to use

API management

For every application that you create, you will have an associated API key and secret (credentials). This API key and secret are needed for authentication before you could access any Medhost API.

To use your API:

  1. Create an application
  2. Select a platform
  3. Enter a description
  4. Choose an API - or group of APIs 
  5. Enter your developing application's callback URL (such as www.example.com)
  6. Add the scope
  7. Select Save

NOTE: In order to use the API, accept the terms and conditions.

Using your API key:

  • Get API key & secret
  • Click API Usage for the current API application 
  • Edit, disable, or delete your API key 
     

You can refer to APIS & Plans for specific details about rate limits and quotas for each API or account plan.

Visit documentation for each API for instructions about directly invoking the specific API.  For examples, refer to the sample code in your preferred language.

Step 3: Get API key & secret

You can edit your application to view the API key and secret.

  1. Click Application 
  2. Choose Edit 
  3. Click Auth
  4. You see the key and secret.

Step 4: Authenticate using OAuth 2.0

Medhost APIs use the OAuth 2.0 protocol for authentication and authorization. There are two approaches for authentication using OAuth 2.0, as explained below:

For running a test with both of these flows, you need the following:

  1. API Key and Secret: this is available after Step 2
  2. OAuth Server
  3. API Server
  4. User's credentials

To get you started, here are some of the dummy user credentials that you can use with any of the following flows

User name: ycc.auto+Arron.Mcpherson.20969@gmail.com

Password: 1q#$%^

Test OAuth Server: https://api.yourcareuniverse.net/security

Test API Server: https://services.yourcareuniverse.net

Approach 1: Authorization code

In this flow, you get access to a refresh token (to generate a new access token) and the validity of the access token on behalf of the authenticated user.

Here’s the flow diagram for obtaining the bearer access token using the authorization code grant type:

 

Listed below are the endpoints you need in order to get the authorization code, the access/refresh token, and token validity.

Relative endpoint paths

1. Authorize Code Endpoint: /oauth/authorize

  • This endpoint gets you the authorization code (through the redirect URL registered during application creation) It needs to be called from a web interface (browser) in order to present the login page for the actual user for authenticating yourself. Then, the authorization code returns in the response using the redirect URL.
  • Method: GET
  • Request query parameters:
Parameter Name Parameter Value
response_type
code
client_id

(associated with registered application)

redirect_uri

(associated with registered application)

2. Get Token Endpoint: /oauth/token

  • This endpoint will return the bearer an access token for the authenticated user based on the input parameters (listed below), along with the refresh token, and access token validity (remaining in seconds).
  • Method: POST
  • Header:
  • Content-Type: application/x-www-form-urlencoded
  • Authorization:
    • Basic 1M2YzOjVlZDU4YTQwYmNhZjRmNzM5YTNhMDIxNTU5NDJlZDkx
    • “1M2YzOjVlZDU4YTQwYmNhZjRmNzM5YTNhMDIxNTU5NDJlZDkx” is Base64 encoded value of ‘API Key:API Secret’
  • Request body:
Parameter Name Parameter Value
grant_type
authorization_code
code

 

redirect_uri

(associated with registered application)

NOTE: It is recommended to always use HTTPS (secured) URL for the callback/redirect URL

Approach 2: Implicit

In this flow, you only get the access token on behalf of the authenticated user.

Here’s the flow diagram for obtaining the bearer access token using the implicit grant type.

Relative endpoint path

1. Authorize code endpoint: /oauth/authorize

  • This endpoint needs to be called from a web interface (browser) in order to present the login page for the user's authentication. Then, the access token returns the response using the redirect URL
  • Query parameters:
Parameter Name Parameter Value
response_type
token
client_id

(associated with registered application)

redirect_uri

(associated with registered application)

NOTE: The refresh token and access token validity would not be accessible in the response when using this implicit flow.

Step 5: Access API

Once the access token has been retrieved on behalf of the user from the OAuth server, all the secured APIs can be accessed subsequently on the API Server.

Pass the header information as listed below for authentication on each API:

Header:

Authorization:

Bearer

AllergyIntolerance API example:

  • Endpoint: /ych/fhir/v1/AllergyIntolerance
  • HTTP Method: GET

Request headers:

  1. Content-Type: application/json+fhir
  2. Authorization: Bearer 

Request format

GET https://services.yourcareuniverse.net/ych/fhir/v1/AllergyIntolerance
[no cookies]
Request Headers:
Connection: keep-alive
Authorization: Bearer a310631c-29ae-4875-a6b5-9a550b008e12
Content-Type: application/json+fhir
Host: services.test.yourcareuniverse.net
User-Agent: Apache-HttpClient/4.5.2 (Java/1.8.0_25)

Response format (application/json+fhir)

 {
  "resourceType": "Bundle",
  "entry": [
    {
      "resource": {
        "resourceType": "AllergyIntolerance",
        "identifier": [
          {
            "system": "YCU",
            "value": "30080"
          }
        ],
        "onset": "2011-01-01T00:00:00+00:00",
        "patient": {
          "reference": "Patient/565b1be3-45e1-4717-bb07-0e1e5aed52ca"
        },
        "substance": {
          "coding": [
            {
              "system": "RXNorm",
              "code": "863538"
            }
          ],
          "text": "PENICILLIN G POTASSIUM"
        },
        "status": "active",
        "category": "medication",
        "lastOccurence": "2011-01-01T00:00:00+00:00",
        "reaction": [
          {
            "manifestation": [
              {
                "coding": [
                  {
                    "system": "SNOMED CT",
                    "code": "424988008"
                  }
                ],
                "text": "Anemia due to substance"
              }
            ]
          }
        ]
      }
    }
  ]
}

 

 

Client Error Format/Structure

Here are the possible error codes, which can come up due to an invalid request

Failing to send a required header/query parameter will result in a 400 Bad Request response.

HTTP/1.1 400 Bad Request

 

Requesting a secured API without valid credentials will result in a 401 Unauthorized response.

HTTP/1.1 401 Unauthorized

 

Requesting data from an unknown instance or an instance where the application is not authorized will result in a 403 Forbidden response.

HTTP/1.1 403 Forbidden

 

Refer the link below for an insight on error response in case of 401 and 403 error codes.

https://www.hl7.org/fhir/DSTU2/operationoutcome.html