Are you ready to dive into the exciting world of querying collections using the MSP REST API?
Fasten your seatbelts because we’re about to embark on a fun and insightful journey together.
In this tutorial, I’ll guide you through the step-by-step process, ensuring that tech and non-tech enthusiasts can easily follow along. Let’s get started!
First things first, let’s set up the foundation for our API requests by defining our variables and authorizing and authenticating an MSP REST API (PHP or Python).
So crack open your preferred text editor, naming and saving a PHP file: query_volunteers.php. Now, go ahead and enter your MSP API Key in the designated area (as shown below).
|
1 2 3 4 5 6 7 8 |
<?php // define MSP API variables $mspApiKey = 'Enter key area'; // Your MSP API Key $apiBaseUrl = "https://api.ministryschedulerpro.com/2/"; // MSP API base URL $endPoint = 'volunteers/list'; // MSP API Endpoint // ... rest of the code goes here ... ?> |
Now that we have our authentication set up, let’s focus on the exciting part: querying MSP collections. We’ll use the volunteers/list endpoint for this example, but you can explore other collections as well.
In order to retrieve specific data, we need to define the fields and where arguments. Don’t worry, it’s not as complicated as it sounds. We’ll use a JSON object to represent these arguments. Here’s an example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
<?php // ... previous code ... // define the 'fields' and 'where' arguments as a JSON object $data = array( "fields" => ["firstName", "lastName", "customFieldValues"], "where" => array( "customFieldValues.a5ddbcec605c7090000" => array( "comparator" => "isLessThan", "value" => "2020-01-01" ) ) ); // ... rest of the code goes here ... ?> |
In this example, we’re requesting the firstName, lastName, and customFieldValues fields for volunteers. Additionally, we’re applying a filter to only retrieve volunteers whose customFieldValues.a5ddbcec605c7090000 field is less than the date “2020-01-01“. Cool, right?
Now that we have our query defined, it’s time to put it into action. We’ll use cURL to make the API request. Here’s the code snippet:
|
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 38 39 40 41 42 43 |
<?php // ... previous code ... // MSP API uses JSON objects as a means of exchange for all endpoints; therefore, json_encode the PHP $data variable value. $postData = json_encode($data); $url = $apiBaseUrl.$endPoint; // set your MSP API Key. Also uncomment the content type if you are attempting to instantiate a request using an MSP API endpoint. $header = array( "Authorization: Bearer $mspApiKey", "Content-Type: application/json" ); $ch = curl_init(); $timeout = 60; // set the url and other options for curl curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST'); // Values: GET, POST, PUT, DELETE, PATCH, UPDATE curl_setopt($ch, CURLOPT_POSTFIELDS, $postData); // uncomment if you are using MSP API endpoint query parameters -- see lines 24-30 // curl_setopt($ch, CURLOPT_POST, true); // uncomment if the previous line is uncommented. ;) curl_setopt($ch, CURLOPT_HTTPHEADER, $header); // execute call and return response data. $result = curl_exec($ch); // close curl connection curl_close($ch); // decode the json response $rez = json_decode($result, true); var_dump($rez); // ... rest of the code goes here ... ?> |
Woohoo! The code snippet above sets up our cURL request using all the MSP API variables and options. We send a POST request to the defined endpoint with our query parameters.
By the way, you can uncomment the lines if you need to include additional MSP API endpoint query parameters.
Once we receive the response, we decode the JSON and store it in the $rez variable. Finally, we can var_dump($rez) to see the result and inspect the data.
And there you have it, my friends! Your query_volunteers.php 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.
You can also apply these steps to other collections by changing the endpoint and adjusting the query parameters. Feel free to experiment and explore the vast possibilities the MSP API offers.
And remember, 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 coding!
P.S. If PHP isn’t your cup of tea, then by all means, please review Querying Collections via the MSP REST API using Python. 😉
Entire Codebase for Querying Collections via the MSP REST API Using PHP.
|
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 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 |
<?PHP /*********************************** **** **** query_volunteers.php **** **** This file allows for authentication using your MSP API Key. **** ***********************************/ // define MSP API variables $mspApiKey = 'Enter key area'; // Your MSP API Key $apiBaseUrl = "https://api.ministryschedulerpro.com/2/"; // MSP API base URL $endPoint = 'volunteers/list'; // MSP API Endpoints // if the endpoint is not defined and still equals the default of `Enter API Endpoint`, then create an empty $endpoint variable. if($endPoint == "Enter API Endpoint"){ $endPoint = ''; } // define the 'fields' and 'where' arguments as a JSON object $data = array( "fields" => ["firstName", "lastName", "customFieldValues"], "where" => array( "customFieldValues.a5ddbcec605c7090000" => array( "comparator" => "isLessThan", "value" => "2020-01-01" ) ) ); // MSP API uses JSON objects as a means of exchange for all endpoints; therefore, json_encode the PHP $data variable value. $postData = json_encode($data); $url = $apiBaseUrl.$endPoint; // set your MSP API Key. Also uncomment the content type if you are attempting to instantiate a request using an MSP API endpoint. $header = array( "Authorization: Bearer $mspApiKey", "Content-Type: application/json" ); // Time to initiate cURL request using MSP API variables $ch = curl_init(); $timeout = 60; // set the url and other options for curl curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, $timeout); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST'); // Values: GET, POST, PUT, DELETE, PATCH, UPDATE curl_setopt($ch, CURLOPT_POSTFIELDS, $postData); // uncomment if you are using MSP API endpoint query parameters -- see lines 24-30 // curl_setopt($ch, CURLOPT_POST, true); // uncomment if the previous line is uncommented. ;) curl_setopt($ch, CURLOPT_HTTPHEADER, $header); // execute call and return response data. $result = curl_exec($ch); // close curl connection curl_close($ch); // decode the json response $rez = json_decode($result, true); var_dump($rez); ?> |