sky-api-python-client
A lightweight, easy to use, Python library for communicating with the Blackbaud Sky API
Loading Sky and load_dotenv
>>> from sky import Sky
>>> from dotenv import load_dotenv
>>> # Loading BB_API_Key from .env file
>>> load_dotenv()
>>> client = Sky(
api_key=None,
file_path='sky_credentials.json',
token_path=".sky-token"
)
Sending a GET Request
>>> roles = client.get(endpoint='roles')
>>> roles['value'][:2]
[{'id': 67454,
'base_role_id': 1,
'hidden': False,
'name': 'Academic Chair'},
{'id': 58802,
'base_role_id': 523,
'hidden': False,
'name': 'Academic Group Manager'}]
Sending a POST Request
>>> new_user = client.post(data = {
"first_name": "API",
"last_name": "User"
})
>>> id = int(new_user.text)
>>> id
5039522
Sending a PATCH Request
>>> update_user = client.patch(data={
"id": id,
"last_name": "NewUser"
})
>>> update_user.satus_code
200
About
This is a python library for connecting the Blackbaud Sky API. Behind the scenes the Blackbaud SKY API uses Authorization Code Flow, which requires the client ID and client secret to get a refresh token and make API calls. The goal of the sky-api-python-client is to abstract details from the OAuth2.0 process so the user can get to coding as quickly as possible.
In order to achieve this a json file with your Blackbaud Application client_id, client_secret, and redirect_uri are required. If you are unsure how to get that information please see the section on SKY API requirements.
The library itself is a wrapper around the authlib
and requests
python libraries. Authlib is used to establish a OAuth2Session, while requests handle the calls to the SKY API. A binary file is used to store your OAuth2Token in between sessions so that this library can be used in non-interactive sessions.
To get or post data from the Sky API you first need to configure your working directory using the guidelines from the Installing Sky. Once that's done, import the Sky class from sky and pass in the value for your sky_credentials
and token_path
if necessary.See Blackbaud's documentations on specifiec references and endpoints that can be passed as arguments in api calls.
Installing sky-api-python-client and setting up your working directory
- Install the latest version of the sky-api-python-client by running
python -m pip install --upgrade sky-api-python-client
- Configure a sky_credentials.json file in your working directory. You can use the sky_credentials_template.json file for reference.
- By default the Sky class looks for a sky_credentials.json file. You can name it something else but you must pass in the new value into the
file_path
argument when initializingSky
.
- By default the Sky class looks for a sky_credentials.json file. You can name it something else but you must pass in the new value into the
- I highly recommend saving the API key you'd like to use in an environment variable called
BB_API_KEY
to avoid exposing your credentials to any script you create. The easiest way to do this is to create a .env file in your working directory and use thepython-dotenv
library to load the .env values into your script.- Please see the example above or go to the python-dotenv documentation.
- When called Sky will automatically check if there's a value for
BB_API_KEY
Using sky-api-python-client
- Once sky-api-python-client is installed you can go directly into coding, even if you have not authorized your app yet.
- The first time that any Sky request is sent (get, post, patch or delete) the sky-api-python-client will check the
token_path
for a valid API token. If it finds one it will proceed with the HTTP request. Otherwise it will check thefile_path
for a valid .json file with your Blackbaud credentials.
- The first time that any Sky request is sent (get, post, patch or delete) the sky-api-python-client will check the
- If Blackbaud credentials are found your default web browser will open and you will be asked to authorize your application. If your sky_crendtials are valid (the client_id, client_secret, and redirect_uri matches what's on your application page) the sky-api-python-client will retrieve a access & refresh token on your behalf and save them for future use in a binary file located on your
token_path
. Otherwise the call will be executed without needing any user interaction
SKY API requirements
-
A Blackbaud Developer subscription key
- If you have not already done so, complete the Getting started guide. This will walk you through the process of registering for a Blackbaud developer account and requesting a subscription to an API product.
- Once approved, your subscription will contain a primary key and secondary key. You can either pass the value of the API key directly into your script or you can save it in a environment variable call BB_API_KEY.
- You can view your subscription keys on your Blackbaud Developer profile.
-
A Blackbaud Developer application ID and application secret
- Register your application in order to obtain the application ID (client ID) and application secret (client secret).
- When you call the Blackbaud Authorization Service from your application, you pass the
redirect_uri
as part of the call. The Blackbaud Authorization Service redirects to this URI after the user grants or denies permission. Therefore, you must whitelist the web address(es) or the authorization will fail. - URIs must exactly match the value your application uses in calls to the Blackbaud Authorization Service.