Skip to content

Commit 35df521

Browse files
gmaciolekdtisza1
gmaciolek
and
dtisza1
authored
Update README.md (#17)
* Update README.md * Add prerequisite section to README * Fix issues with code block highlighting sections * Update README.md * Update README.md Co-authored-by: Dave Tisza <dtisza@fearless.tech>
1 parent 713e07b commit 35df521

1 file changed

Lines changed: 89 additions & 79 deletions

File tree

‎README.md‎

Lines changed: 89 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,109 @@
1-
# Blue Button API SDK (Python)
1+
# Python SDK for Blue Button 2.0 API
2+
This Python software development kit (SDK) provides tools and resources for developers integrating with the [CMS Blue Button 2.0 (BB2.0) API](https://bluebutton.cms.gov/developers/).
23

3-
# Table of contents
44

5-
1. [Descritpion](#description)
6-
2. [Installation](#installation)
7-
3. [Configuration](#configuration)
8-
4. [Usages: Obtain Access Grant, Probe Scope, and Access Data](#usages)
9-
5. [A Complete Sample App](#samples)
10-
6. [API Versions and Environments](#versions_and_environments)
11-
7. [SDK Development](#sdk_devel)
5+
# Table of Contents
126

13-
## Description <a name="description"></a>
7+
- [Prerequisites](#prerequisites)
8+
- [Installation](#installation)
9+
- [Configuration Parameters](#configuration-parameters)
10+
- [Configuration Methods](#configuration-methods)
11+
- [Usage](#usage)
12+
- [Sample App](#sample-app)
13+
- [SDK Development](#sdk_devel)
14+
- [About](#about)
15+
- [Help and Support](#help)
1416

15-
This is an SDK for interacting with the [CMS Blue Button 2.0 API](https://bluebutton.cms.gov/developers/).
16-
The API allows applications to obtain a beneficiary's (who has login account with medicare.gov) grant
17-
to access their medicare claims data - through the OAuth 2.0 [(RFC 6749)](https://datatracker.ietf.org/doc/html/rfc6749) authorization flow.
1817

19-
By using the SDK, the development of applications accessing the Blue Button 2.0 API can be greatly simplified.
18+
## Prerequisites <a name="prerequisites"></a>
19+
20+
You'll need a sandbox account and sample access token to access data from the Blue Button 2.0 API.
21+
22+
To learn how to create a sandbox account and generate a sample access token, see **[Try the API](https://bluebutton.cms.gov/developers/#try-the-api)**.
2023

21-
Note: In following OAuth 2.0 best practices, the PKCE extension [(RFC 7636)](https://datatracker.ietf.org/doc/html/rfc7636) is always enabled.
2224

2325
## Installation <a name="installation"></a>
2426

2527
```bash
2628
$ pip install cms-bluebutton-sdk
2729
```
2830

29-
## Configuration <a name="configuration"></a>
31+
## Configuration Parameters<a name="configuration-parameters"></a>
3032

31-
The SDK needs to be properly configured to work.
33+
Required SDK configuration parameters include:
3234

33-
The configuration parameters are:
35+
| Parameter | Value | Default |Description |
36+
| ------------- | ------------------------------- |----| --------------------------------------- |
37+
| `environment` | `SANDBOX` or `PRODUCTION` |`SANDBOX` | Blue Button 2.0 API environment |
38+
| `version` | `1` or `2` | `2` | Blue Button 2.0 version |
39+
| `client_id` | *`foo`* | |OAuth2.0 client ID of the app |
40+
| `client_secret` | *`bar`* | |OAuth2.0 client secret of the app |
41+
| `callback_url` | *`https://www.example.com/callback`* | |OAuth2.0 callback URL of the app |
3442

35-
- The app's credentials - client id, client secret
36-
- The app's callback url
37-
- The version number of the API
38-
- The app's environment (the BB2.0 web location where the app is registered)
39-
- The FHIR call retry settings
40-
- Enable / Disable Token refresh if FHIR request processing detected the access token expired
4143

42-
| Parameter | Value | Comments |
43-
| ------------- | ------------------------------- | --------------------------------------- |
44-
| environment | "SANDBOX" or "PRODUCTION" | BB2 API environment (default="SANDBOX") |
45-
| version | 1 or 2 | BB2 API version (default=2) |
46-
| client_id | "foo" | oauth2 client id of the app |
47-
| client_secret | "bar" | oauth2 client secret of the app |
48-
| callback_url | "https://www.fake.com/callback" | oauth2 callback URL of the app |
44+
### Access Token Refresh on Expire
45+
SDK FHIR requests check whether the access token is expired before the data end point call. By default, if the access token is expired, the token in the current token object refreshes. Disable token refresh by setting `token_refresh_on_expire` to `false`.
4946

50-
For application registration and client id and client secret, please refer to:
51-
[Blue Button 2.0 API Docs - Try the API](https://bluebutton.cms.gov/developers/#try-the-api)
47+
### FHIR Requests Retry Settings
5248

53-
Auth Token Refresh on Expire:
49+
Retry is enabled by default for FHIR requests. The folllowing parameters are available for exponential back off retry algorithm.
5450

55-
SDK FHIR requests will check if the access token is expired before the data end point call, if the access token is expired, then a token refresh is performed with the refresh token in the current auth token object, this behavior can be disabled by setting configuration parameter as below:
51+
| Retry parameter | Value (default) | Description |
52+
| ----------------- | -------------------- | -------------------------------- |
53+
| `backoff_factor` | `5` | Backoff factor in seconds |
54+
| `total ` | `3` | Max retries |
55+
| `status_forcelist` | [`500`, `502`, `503`, `504`] | Error response codes to retry on |
5656

57-
"token_refresh_on_expire": false
57+
The exponential backoff factor (in seconds) is used to calculate interval between retries using the formula `backoff_factor * (2 ** (i - 1))` where `i` starts from 0.
5858

59-
By default, token_refresh_on_expire is true.
59+
Example:
6060

61-
FHIR requests retry:
61+
A`backoff_factor` of 5 seconds generates the wait intervals: 2.5, 5, 10, ...
6262

63-
Retry is enabled by default for FHIR requests, retry_settings: parameters for exponential back off retry algorithm
63+
To disable the retry, set `total = 0`
6464

65-
| retry parameter | value (default) | Comments |
66-
| ----------------- | -------------------- | -------------------------------- |
67-
| backoff_factor | 5 | back off factor in seconds |
68-
| total | 3 | max retries |
69-
| status_forcelist | [500, 502, 503, 504] | error response codes to retry on |
65+
### Environments and Data
66+
67+
The Blue Button 2.0 API is available in V1 and V2 in a sandbox and production environment.
68+
69+
- Sandbox location: https://sandbox.bluebutton.cms.gov
70+
- Production location: https://api.bluebutton.cms.gov
71+
72+
Version data formats:
73+
74+
- V1: FHIR STU2
75+
- V2: FHIR R4
76+
77+
Sample configuration JSON with default version and environment:
78+
79+
```
80+
{
81+
"clientId": "foo",
82+
"clientSecret": "bar",
83+
"callbackUrl": "https://www.fake.com/",
84+
}
85+
86+
```
7087

71-
the exponential back off factor (in seconds) is used to calculate interval between retries by below formular, where i starts from 0:
88+
If needed, you can set your application's target environment and API version.
7289

73-
backoff factor * (2 ** (i - 1))
90+
Example:
7491

75-
e.g. for backoff_factor is 5 seconds, it will generate wait intervals: 2.5, 5, 10, ...
92+
```
93+
{
94+
"clientId": "foo",
95+
"clientSecret": "bar",
96+
"callbackUrl": "https://www.fake.com/",
97+
"version": "2",
98+
"environment": "PRODUCTION"
99+
}
76100
77-
to disable the retry: set total = 0
101+
```
78102

79-
There are three ways to configure the SDK when instantiating a `BlueButton` class instance:
103+
## Configuration Methods<a name="configuration-methods"></a>
104+
There are three ways to configure the SDK when instantiating a `BlueButton` class instance.
80105

81-
* Python Dictionary:
106+
### Python Dictionary
82107
- A dictionary of configuration key:value pairs can be used.
83108
- Configuration values can be provided from your own application's configuration method.
84109
- Example code:
@@ -96,7 +121,7 @@ There are three ways to configure the SDK when instantiating a `BlueButton` clas
96121
}
97122
}
98123
```
99-
* JSON config file:
124+
### JSON config file
100125
- This is using a configuration file that is in a JSON format.
101126
- This is stored in a local file.
102127
- The default location is in the current working directory with a file name: .bluebutton-config.json
@@ -120,7 +145,7 @@ There are three ways to configure the SDK when instantiating a `BlueButton` clas
120145
}
121146
```
122147

123-
* YAML config file:
148+
### YAML config file
124149
- This is using a configuration file that is in a YAML format.
125150
- This is stored in a local file.
126151
- The default location is in the current working directory with a file name: .bluebutton-config.yaml
@@ -139,7 +164,7 @@ There are three ways to configure the SDK when instantiating a `BlueButton` clas
139164

140165
## Sample Usage: Obtain Access Grant, Probe Scope, and Access Data <a name="usages"></a>
141166

142-
Below are psuedo code snippets showing SDK used with python server and flask.
167+
Below are code snippets showing the SDK used with Python server and Flask.
143168

144169
```python
145170
from flask import Flask
@@ -257,39 +282,24 @@ if __name__ == '__main__':
257282
app.run(debug=True, host='0.0.0.0', port=3001)
258283
```
259284

260-
## A Complete Sample App <a name="samples"></a>
261-
262-
A Python React sample app can be found at:
263-
[CMS Blue Button Python Sample App](https://github.com/CMSgov/bluebutton-sample-client-python-react)
264-
265-
## API Versions and Environments <a name="versions_and_environments"></a>
266-
267-
Can be selected for environments: PRODUCTION and SANDBOX.
285+
## Sample App <a name="samples"></a>
268286

269-
The Blue Button API is available in versions v1 and v2.
287+
For a complete Python React sample app, see [CMS Blue Button Python Sample App](https://github.com/CMSgov/bluebutton-sample-client-python-react).
270288

271-
The data served from v1 is in FHIR STU2 format, and data from v2 is in FHIR R4 format.
272289

273-
An application's target environment and API version can be set in the SDK configuration as shown by the JSON example below:
290+
## SDK Development <a name="sdk_devel"></a>
274291

275-
```json
276-
{
277-
"clientId": "foo",
278-
"clientSecret": "bar",
279-
"callbackUrl": "https://www.fake.com/",
280-
"version": "2",
281-
"environment": "PRODUCTION"
282-
}
283-
```
292+
Documentation for BlueButton 2.0 team members and others developing the SDK can be found at [README-sdk-dev.md](./README-sdk-dev.md).
284293

285-
If not included, the default API version is v2, and the default environment is SANDBOX.
294+
## About the Blue Button 2.0 API <a name="about"></a>
286295

287-
Web location of the environments:
296+
The [Blue Button 2.0 API](https://bluebutton.cms.gov/) provides Medicare enrollee claims data to applications using the [OAuth2.0 authorization flow](https://datatracker.ietf.org/doc/html/rfc6749). We aim to provide a developer-friendly, standards-based API that enables people with Medicare to connect their claims data to the applications, services, and research programs they trust.
288297

289-
[PRODUCTION Environment: https://api.bluebutton.cms.gov](https://api.bluebutton.cms.gov)
298+
## License
299+
The CMS Blue Button 2.0 Python SDK is licensed under the Creative Commons Zero v1.0 Universal. For more details, see [License](https://github.com/CMSgov/cms-bb2-python-sdk/blob/main/LICENSE).
290300

291-
[SANDBOX Environment: https://sandbox.bluebutton.cms.gov](https://sandbox.bluebutton.cms.gov)
301+
*Note: We do our best to keep our SDKs up to date with vulnerability patching, but you are responsible for conducting your own review and testing before implementation.*
292302

293-
## SDK Development <a name="sdk_devel"></a>
303+
## Help and Support <a name="help"></a>
294304

295-
Documentation for BB2 team members and others developing the SDK can be found here: [README-sdk-dev.md](./README-sdk-dev.md)
305+
Got questions? Need help troubleshooting? Want to propose a new feature? Contact the Blue Button 2.0 team and connect with the community in our [Google Group](https://groups.google.com/forum/#!forum/Developer-group-for-cms-blue-button-api).

0 commit comments

Comments
 (0)