Interacting with an External API with WordPress

The ability to utilize another company’s API (Application Programming Interface) is an extremely useful skill in any programmer’s arsenal. An API is essentially an interface a company provides that allows programmers to connect to their services in order to receive data and perform actions. There are different types of APIs, but in most cases, it will simply be an assortment of functions or resources that you access with HTTP requests.

The most common and often the only way to access an API is through HTTP requests, especially using GET and POST requests. There are also PUT, HEAD, DELETE, PATCH, and OPTIONS requests, but for the vast majority of API interactions you can get by just using GET and POST. A GET request is used to request data from a resource. The API you’re using might provide endpoints where you can send GET requests to get data. Let’s say the API has an endpoint such as https://www.testapi.com/users and the documentation tells you that this endpoint is used to retrieve information about users for the site. You can then send GET requests to receive specific data about a single or even multiple users. With GET requests, you use something called a query string to append values to a URL in order to request the information you want. In this case, you might send a GET request to the URL https://www.testapi.com/users?username=test_user. Then, the response you received would contain whatever information the API provided about their users for the user test_user. So, how do we make this request?

There are a few different built-in WordPress functions you can use to send HTTP requests, and even some plugins you could use if you’re not comfortable writing code. Personally, I like using the wp_remote_get and wp_remote_post functions for GET and POST requests. wp_remote_get is quite simple. It accepts two arguments, a URL argument and an optional array to override the default options for the request. Here’s the documentation on the function. So, to get the user with a username of test_user using a GET request, we could simply do the following:

$url = 'https://www.testapi.com/users?username=test_user';

$response = wp_remote_get( $url );

Then, we can parse through the response to get the information we need. We’d likely want to do some error checking on the response to make sure we actually received data back, but otherwise, that’s really all there is to it! You may also need to adjust some of the default options, but for most purposes, they should be fine. This same process could be used for any of the other GET resources available through the API. What you’re able to do with the API is entirely dependent on what the company has chosen to make available to you, so it’s really just a matter of reading through the API documentation to find what’s applicable to what you’re trying to do. You might use GET requests to get posts, comments, photos, and even something like weather data.

POST requests are a bit trickier but also allow you to do a lot more with an API. An HTTP POST request is used to send data to a server in order to create or update a resource. So going back to our user example, instead of just getting the data for test_user, we could have used a POST request to update some aspect of that user. POST requests involve sending data in the request body of the HTTP request and are thus more secure than GET requests since you can’t see what’s being sent just by looking at the URL. Let’s say we want to update something like the user’s password through an API. As you would have seen when receiving the data from the GET request, all of the data associated with the user is set up in some sort of data structure, likely an array or object. So sending a POST request to update the user is just a matter of sending updated data for that data structure. If password is a field associated with the user, there is likely a password key in the data structure. So, your POST request might look something like this:

$url = 'https://www.testapi.com/users';

$response = wp_remote_post( $url,
	array(
		'body' => array(
			'username' => 'test_user',
			'password' => 'testpassword'
		)

	)
);

It depends on the API, but the response will likely contain the updated data structure.

Using an API can sometimes be a bit tricky. There is often no real consistency in data structure across different companies’ APIs, so a big part of starting to use one is simply figuring out the proper structure to send your data and how to access what you want from the data you receive back. If you’re working in WordPress, one method of doing this is to simply var_dump the data you receive. This can work fine if you’ve already nailed down the structure for sending data, but that can be tricky too. One tool I love to use for working with APIs is called Postman. Postman does all of the data structuring for you when sending HTTP requests so you can spend more time figuring out what data you need instead of tweaking your code to get it just right. With Postman, you can simply create a new GET/POST request, enter the URL endpoint, add either the key/value pairs or the body data, and click send. You can then see the response and choose the display format for it. You can even write tests to automatically alert you if the data you received is what you wanted or create global variables so you don’t have to write out the URL for every individual test. Postman is an excellent resource for familiarizing yourself with the structure of an API before you build the data structures yourself through code. Here’s a great tutorial for getting started with Postman.

While they can seem overwhelming, APIs are an excellent resource for any application. There’s truly no limit to the data you have access to with APIs since just about every company with some sort of tech background provides an external API. There’s even a WordPress API you can use! APIs connect your website or application to the data of the web, and if you know how to use them, you can become a much more powerful and dynamic developer. Next step, figure out what to do with all that data!