Welcome back. In today’s tutorial, I’ll help you unlock the door and step into the world of querying collections using the MSP REST API.
But before we begin, please ensure you have checked all the requirement checkboxes from the Getting Started page. Got those boxes checked and requirements locked in?
Well, then, let’s get started!
One of the first actions I’ll have you take is setting up the foundation for our API requests using Python.
If you’re not that familiar with Python, then no worries at all. Python scripting and programming are relatively easy to learn. And if not, there is always old faithful in learning to script and program using PHP.
To successfully query collections using Python, we must authenticate using our MSP API Key. Check our FAQs if you have questions about how to gain access to your MSP API Key.
Think of the MSP API Key as a unique key that unlocks the API’s awesomeness of accessing your MSP data. So go ahead and grab your MSP API Key and let’s get started.
Ready? Great!
|
1 2 3 4 5 6 |
# define MSP API variables msp_api_key = 'Enter key area' # Your MSP API Key api_base_url = "https://api.ministryschedulerpro.com/2/" # MSP API base URL end_point = 'volunteers/list' # MSP API Endpoint # ... rest of the code goes here ... |
Now that we have defined our authentication variable for the MSP API Key, let’s move on to the exciting part: querying the volunteers collection. We’ll be using the volunteers/list endpoint in this tutorial example, but feel free to explore other MSP collections.
To request and retrieve specific endpoint data, we must next define the fields and where arguments so we can narrow down the number of records or the precise record to be returned.
But don’t panic on me, it’s not as complicated as it sounds. We’ll use the following data dictionary to represent these arguments:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# ... previous code ... # define the 'fields' and 'where' arguments as a dictionary data = { "fields": ["firstName", "lastName", "customFieldValues"], "where": { "customFieldValues.a5ddbcec605c7090000": { "comparator": "isLessThan", "value": "2020-01-01" } } } # ... rest of the code goes here ... |
In this tutorial example, we request the volunteers’ firstName, lastName, and customFieldValues fields. We’re also applying a filter only to retrieve volunteers whose customFieldValues.a5ddbcec605c7090000 field is less than the date “2020-01-01“.
Pretty neat, huh? Let’s keep the coding party going!
Now that we have our query defined, it’s time to put it into action. We’ll be using the requests library in Python to make the API request. Here’s the code snippet you need for that:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
import requests # ... previous code ... # MSP API uses JSON objects as a means of exchange for all endpoints, so let's convert the Python `data` variable to JSON. post_data = json.dumps(data) url = api_base_url + end_point # Set the headers with your MSP API Key. You can also uncomment the content type if you're using an MSP API endpoint. headers = { "Authorization": "Bearer " + msp_api_key, "Content-Type": "application/json" } # Execute the request and get the response response = requests.post(url, data=post_data, headers=headers) # Get the response data in JSON format result = response.json() # Print the result print(result) # ... rest of the code goes here ... |
The code snippet above sets up our request using all the MSP API variables and options. We send a POST request to the defined endpoint with our query parameters.
In addition, feel free to uncomment the respective lines if you need to include additional MSP API endpoint query parameters.
Once we receive the response, we can access the JSON data using the .json() method and store it in the result variable. Finally, we can print the result to see the data.
Woohoo! You’ve made it to the end.
And there you have it, my friends! Your query_volunteers.py file is now ready to be accessed via a web browser and tested.
You should now be able to successfully query the volunteers collection using the MSP REST API in Python.
Feel free to experiment and explore if you so desire. Try applying these steps to other MSP collections by changing the endpoint and adjusting the query parameters. The MSP REST API is a world full of vast possibilities.
Lastly, remember that this tutorial focuses on simplicity, so error checking has been omitted. But don’t worry, we’ll cover error handling in more advanced tutorials.
Feel free to reach out if you have any questions or encounter technical roadblocks along the way.
Happy querying!
P.S. If PHP isn’t your cup of tea, then by all means, please review Querying Collections via the MSP REST API using PHP. 😉
Entire Codebase for Querying Collections via the MSP REST API Using Python.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
import requests # define MSP API variables msp_api_key = 'Enter key area' # Your MSP API Key api_base_url = "https://api.ministryschedulerpro.com/2/" # MSP API base URL end_point = 'volunteers/list' # MSP API Endpoint # define the 'fields' and 'where' arguments as a dictionary data = { "fields": ["firstName", "lastName", "customFieldValues"], "where": { "customFieldValues.a5ddbcec605c7090000": { "comparator": "isLessThan", "value": "2020-01-01" } } } # MSP API uses JSON objects as a means of exchange for all endpoints; therefore, json encode the Python `data` variable value. post_data = json.dumps(data) url = api_base_url + end_point # set your MSP API Key. Also uncomment the content type if you are attempting to instantiate a request using an MSP API endpoint. headers = { "Authorization": "Bearer " + msp_api_key, "Content-Type": "application/json" } # execute the request and get the response response = requests.post(url, data=post_data, headers=headers) # get the response data in JSON format result = response.json() # print the result print(result) |