Making API calls with cURL is actually a lot more simple than most people things. In this tutorial we will walk through an example of to make an API call to the GitHub API and get a repositories README file contents. This tutorial will be done in the scope of a WordPress shortcode that you add to your functions.php file.
The code that we will go over is actually taken from my own plugin, DobsonDev Shortcodes. I recently got an email from someone asking for this feature so I implemented it for them because I thought it was a great idea. I thought I would share what I found about API calls with cURL on my blog here so that others could use the basic knowledge for their own API calls.
In the future I would like to look at POST calls as well since we only go over GET calls in this tutorial. I would also like to do a whole series where we create our own API and then implement the calls for that API in some kind of WordPress capacity.
Getting Started
The first thing we have to do is create our shortcode function within WordPress. If you haven’t done this before, I have a previous tutorial that goes more in depth on creating your own shortcodes and how they work so you might want to give that a read first.
For the sake of this example this code will be added to our functions.php file as mentioned above, but ideally this would actually go into a plugin.
Basically what we need is the owner of the repository and the actual repository name, so these will be our shortcode attributes that we need to extract. You can see the skeleton of the function below:
Using cURL for API Calls
Before using cURL for your own calls I would also recommend you take a quick look at the PHP manual entry for cURL. It contains all the information could you ever want since their is quite a bit that you can do with cURL. I would especially recommend looking at the PHP manual page for curl_setopt_array() since it is extremely important for API calls.
What We Need
Before creating our $curl object it’s important to know what we are going to need to do in order to get the data we want. In order to use the GitHub API, we need to make sure we set the User-Agent Header because this is required by all GitHub API calls. The documentation recommends that we set this to either the Username or the Repository that we are trying to get – which is perfect because we are already getting that information from our shortcode attributes.
We also need to make sure we set the Return-Transfer Header to true(1) so that we actually get content back from the API call. If this is set to false then all we get as a return is true if the call succeeded or false if the call failed. When its set to true we get the data (as JSON) when it success and we will get false when it fails.
Finally we also of course need the URL for the API call. This will be in the form of https://api.github.com/repos/OWNER/REPO/readme and we will simply replace the OWNER and REPO with the variables we set from our shortcode attributes.
Making Our API Call
Now that we know what we have to do and what we need, all we have to do is convert that into code. Take a look below as the code for the API call and then I’ll explain what’s happening:
The first thing we do is create a $curl variable with the curl_init() function. We then add the required headers as described above. We set the Return-Transfer Header to true(1), the User-Agent Header to $repo since that’s whats recommend by GitHub (you can also set it to the $owner), and finally we create the URL to make the call to by putting the $owner and $repo variables in position.
After we setup our options (the setopt part of curl_setopt_array is short for setup options) we execute our API call and save the response as $response. At this point we have a bunch of JSON (or false if the call failed) saved into that variable.
Using the Data
Now that we have the data we need to use it. The first thing we want to check for is if the API call was successful or not. If it failed then $response will be false, so that’s an easy enough check.
If the call was successful we want to decode the JSON and get the content of the README file. The content of the README file will be in base64 so we also need to decode that.
The code we now have will display the markdown out onto the page. If you want to actually convert the markdown to HTML then I would highly recommend using the Parsedown PHP library. All you have to do is include the Parsedown.php file and create a new Parsedown object. You can then convert the markdown into HTML to display on the page.
Now our code will grab the content and convert the markdown to HTML.
Conclusion
As mentioned at the top of this article – in the future I would like to look at POST calls as well since we only go over GET calls in this tutorial. I would also like to do a whole series where we create our own API and then implement the calls for that API in some kind of WordPress capacity. There is a lot more to API calls with cURL than what I’ve gone over here but hopefully this practical example will get you started on figuring out your own API calls.
As always thank you for reading and please share it around as much as you can! Please feel free to put any suggestions or ideas for future tutorials in the comments section below.