U.S. Flag

An official website of the United States government

Image

Postman and Swagger Tutorial

Postman Instructions
Sandbox and the Onboarding Process
What does this instruction guide contain?
Step 1: Postman Instructions
Downloading Postman
Creating a new collection
Saving a request
Posting a request
Step 2: Swagger Instructions
Authorize a bearer token
Export a Job ID
Check the status of your job
Download your Job ID
Questions?

Postman Instructions

Sandbox and the Onboarding Process

After attesting and electing an AB2D Data Operations Specialist (ADOS), a PDP organization must demonstrate their ability to use the API to access Production by successfully retrieving synthetic claims data from the test (Sandbox) environment. In order to verify this requirement, PDP organizations must provide the AB2D team with the Job ID from a successful run in the test (Sandbox) environment.

AB2D Synthetic Data

AB2D provides four sample contracts that have been designed to provide synthetic data for testing purposes.

Simple Datasets- Two Contracts

This dataset provides contracts with a varying number of beneficiaries containing simple approximations of AB2D data. These contracts are ideal to test the stress of retrieving and downloading different sized data files. The data in these API payloads will not reflect the distribution of disease and demographic information you can expect from production data.

PDP Sponsor Contract Number of Benes
PDP-100 Z0000 100
PDP-10000 Z0010 10,000

Advanced Datasets- Two Contracts

This dataset provides contracts with sample data that is a more accurate representation of AB2D production data. They follow AB2D’s Bulk FHIR format and contain a more realistic distribution of disease and demographic information.

PDP Sponsor Contract Number of Benes
PDP-1001 Z1001 600-800
PDP-1002 Z1002 600-800
What does this instruction guide contain?

These instructions will guide you through the process of obtaining a JSON web token (JWT), also referred to as a bearer token, using Postman. Postman offers a Graphical User Interface (GUI) and provides an easy entrance point for users. Once complete, this token will be used to pull synthetic claims data by accessing test (Sandbox) API endpoints using another application called Swagger. The instructions below: Postman (Step 1) + Swagger (Step 2) are needed to access the Sandbox environment.

Step 1: Postman Instructions

The Postman directions below are broken up into the following sections:

  • Downloading Postman
  • Creating a new collection
  • Saving a request
  • Posting a request
Downloading Postman

Go to the Postman site here to download and install the app version of Postman. Because only the app version of Postman is allowed in Production, we promote the use of this version in Sandbox as well. The web version is available to you in Sandbox, but it will not be in Production. The directions below follow along with the app version of Postman.

download postman

You will then be directed to an account sign-in page. Note, you are able to directly access the app and skip sign-in by clicking the link at the bottom of the page as shown below.

postman signin
Creating a new collection

Click on the orange + New button in the top left corner of the app.

postman create new button

Choose Create New to create a new Collection:

postman create new collection

Configure as follows:
Name: ab2d
Choose: Create.

postman create new
                collection details

In the left hand panel, click on the three dot’s next the ab2d node you just created and choose Add Request:

postman new request
Saving a request

Configure the “SAVE REQUEST” page as follows:

  • Request name: retrieve-a-token
  • Select: Save to ab2d at bottom right corner.
postman save new request
Posting a request

Click on GET, retrieve-a-token under the ab2d node and immediately, a new tab will appear to the right.

postman post a request

Alter the GET request to a POST request:

postman change get to post

In the bar next to POST enter the following URL:
https://test.idp.idm.cms.gov/oauth2/aus2r7y3gdaFMKBol297/v1/token

postman enter url

Configure the Params tab as follows:

Key Value
grant_type client_credentials
scope clientCreds

postman enter params

Configure the Headers tab as follows:
Choose one of the sample Base64-encoded credentials from a sample PDP Sponsor. This will be placed under the Value column by Authorization.

Simple Datasets
PDP Sponsor Base64-encoded id: password
PDP-100 MG9hMnQwbHNyZFp3NXVXUngyOTc6SEhkdVdHNkxvZ0l2RElRdVdncDNabG85T1lNVmFsVHRINU9CY3VIdw==
PDP-10000 MG9hMnQwbG05cW9BdEpIcUMyOTc6eWJSNjBKbXRjcFJ0NlNBZUxtdmJxNmwtM1lEUkNaUC1XTjFBdDZ0Xw==

Advanced Datasets
PDP Sponsor Base64-encoded id: password
PDP-1001 MG9hOWp5eDJ3OVowQW50TEUyOTc6aHNrYlB1LVlvV2ZHRFkxZ2NRcTM0QmZJRXlNVnVheXU4N3pXRGxpRw==
PDP-1002 MG9hOWp6MGUxZHlOZlJNbTYyOTc6c2huRzZOR2tIY3UyOXB0RHNLS1JXNnE1dUZKU1NwSXBkbF9LNWZWVw==

Key Value
Content-Type application/x-www-form-urlencoded
Accept application/json
Authorization Basic {Base64-encoded id:password}

postman headers filled

Select Send.
In the body below you should see a token type, expires in statement, an access token, and scope statement as shown below:

postman response body

You will use this bearer token, specified by the access_token value (in the next hour), to access Sandbox endpoints in Swagger, which we explain how to use below.

Step 2: Swagger Instructions

The Swagger directions below are broken into the following sections:

  • Authorize your bearer token
  • Export a Job ID
  • Check the status of a job
  • Download your Job ID
Authorize a bearer token

First - you must access the AB2D Swagger site by going here. Click “authorize” in the top right corner.

swagger authorize

Use the bearer token (retrieved in the last 24 hours by you, and no other user) to authorize entry into the Sandbox endpoints. You will place this in the box under Value, adding the word Bearer before the token.

swagger authorize api key

Be sure to leave a space between the word Bearer and the actual bearer token. Also remove any quotes from the token itself. Click Authorize.

swagger enter api key

You will see the following message:

swagger authorize response

Click Close to close the window.

Export a Job ID

AB2D supports both R4 and STU3 versions of the FHIR standard in both sandbox and production environments. FHIR R4 is available using v2 of AB2D while FHIR STU3 can be accessed via AB2D v1 which is typically indicated in an endpoint’s URL. Users are recommended to use AB2D v2 thus we will use that version in the examples/screenshots provided below. Users can select the AB2D API version they’d like to use in the Swagger interface by navigating to the dropdown menu in the right-hand corner of the page. Detailed descriptions of AB2D v1 (STU3) and AB2D v2 (R4) can be accessed in the AB2D Document Repository in Github.

Open the Export menu to view all possible endpoints:

swagger export menu

Choose /api/v2/fhir/Patient/$export to initiate a Part A & B bulk claim export job. Then choose to Try it out in the right hand corner.

swagger export parameters

The default options are fine in this case with the exception of the _since date. A good value for this contract is

2021-01-01T00:00:00.000-05:00
Enter this value and click the big blue bar to Execute.

swagger execute

In the responses, look at the first code provided under Server response. Below that are all the other possible responses. The correct response should be a 202, which means Accepted. This means the job has been created.

swagger response

From the information provided in the response, copy the Job ID from within the status request. Format:
content-location: http://sandbox.ab2d.cms.gov/api/v2/fhir/Job/{job id}/$status

Example:
content-location:
http://sandbox.ab2d.cms.gov/api/v2/fhir/Job/eeb77c0d-d9e2-4a7c-b6e6-c4ab8e0917ca/$status

Check the status of your job

While these are test jobs and most will run quickly, it is good practice to understand the steps associated with running a job, including checking its status.

Click on the Status menu to view the status endpoints:

swagger job status

Copy the Job ID from the Export step. Click on the GET /api/v2/fhir/{jobUuid}/$status endpoint, click Try it out and paste the Job ID into the box provided.

swagger endpoint status

Click on the big blue bar labeled Execute.

swagger try it out

In the responses, view the first value. This is the server response. There are two possible values, 202 or 200. If the response is 202, this means that the job is still in progress. It will give you an indication of the job progress from 1 to 100%.

An example of a partially finished job (36%) would be:

partially finished status

You will need to re-click on the Execute blue bar periodically until the status returns a 200. This means the job is done and the response will contain a list of files

swagger response

These files can then be downloaded and contain the claim records for our sample job.

Download your Job Files

Click on the Download menu in swagger. Select the GET /api/v2/fhir/Job/{jobUuid}/file/{filename} endpoint to download a file. Click Try it out. Enter the Job ID of the job you created and the file name returned in the status, then press the Execute big blue bar.

swagger download

It might take a while for the file to be downloaded depending on how big the job is. The Server response value should be a 200 and the Response body will contain a link to the claims data. To download the data into a file, click on the Download file link. This will be saved as an ndjson (new line delimited JSON, also known as JSON lines) file in your downloads. This data format will be identical to the production data. Only the Job ID from this file is needed - please send the Job ID to the AB2D team per the instructions emailed to your organizations assigned ADOS.

swagger response body

Questions?

Having issues or concerns - please get in touch.
ab2d@cms.hhs.gov - direct email
AB2D Google Group - join the conversation