HTTP API and Transients

Summary: Learning about the HTTP API and Transients in WordPress.

HTTP API

The HTTP API in WordPress is a powerful set of functions that enable us to make HTTP requests to external servers and handle responses within WordPress. It provides a unified and consistent way to perform HTTP operations such as GET, POST, PUT, DELETE and more using a range of available transports (such as cURL, fsockopen, and Streams). This API is particularly useful for interacting with external RESTful APIs, fetching remote data, submitting forms, and other tasks that require communication with external servers.

GETting data from an API

GETting data is made incredibly simple in WordPress through the wp_remote_get() function. This function takes the following two arguments:

1. $url – Resource to retrieve data from. This must be in a standard HTTP format
2. $args – OPTIONAL – We may pass an array of arguments in here to alter behavior and headers, such as cookies, follow redirects, etc.

The following defaults are assumed, though they can be changed via the $args parameter.

• method – GET
• timeout – 5 – How long to wait before giving up
• redirection – 5 – How many times to follow redirects.
• httpversion – 1.0
• blocking – true – Should the rest of the page wait to finish loading until this operation is complete?
• headers – array()
• body – null
• cookies – array()

$response = wp_remote_get( 'https://api.github.com/users/b1ink0' );

GET the body you always wanted

Just the body can be retrieved using wp_remote_retrieve_body(). This function takes just one parameter, the response from any of the other wp_remote_X functions where retrieve is not the next value.

$response = wp_remote_get( 'https://api.github.com/users/b1ink0' );
$body     = wp_remote_retrieve_body( $response );

GET the response code

We may want to check the response code to ensure our retrieval was successful. This can be done via the wp_remote_retrieve_response_code() function:

$response = wp_remote_get( 'https://api.github.com/users/b1ink0' );
$http_code = wp_remote_retrieve_response_code( $response );

GET using basic authentication

APIs that are secured more provide one or more of many different types of authentication. A common, though not highly secure, authentication method is HTTP Basic Authentication. It can be used in WordPress by passing ‘Authorization’ to the second parameter of the wp_remote_get() function, as well as the other HTTP method functions.

$args = array(
    'headers' => array(
        'Authorization' => 'Basic ' . base64_encode( YOUR_USERNAME . ':' . YOUR_PASSWORD )
    )
);
wp_remote_get( $url, $args );

POSTing data to an API

POSTing data is done using the wp_remote_post() function, and takes exactly the same parameters as wp_remote_get(). It should be noted here that we are required to pass in ALL of the elements in the array for the second parameter. 

$response = wp_remote_post( 'http://your-contact-form.com', $args );

Transients

The Transients API is very similar to the Options API but with the added feature of an expiration time, which simplifies the process of using the wp_options database table to temporarily store cached information.

Saving Transients

set_transient( $transient, $value, $expiration );

• $transient (string): Transient name.
  Expected to not be SQL-escaped. Must be 172 characters or fewer in length.
• $value (array|object): Data to save, either a regular variable or an array/object.
  The API will handle serialization of complex data for we.
• $expiration (integer): The maximum of seconds to keep the data before refreshing.
  Transients may expire before the $expiration (Due to External Object Caches, or database upgrades) but will never return their value past $expiration.

Fetching Transients

get_transient( $transient );

$transient: the unique slug used while saving the transient with set_transient().

Removing Saved Transients

delete_transient( $transient );

$transient: the unique name used when saving with set_transient().