Revise WordPress Core APIs

Summary: Revising WordPress Core APIs like HTTP API, Transient API, Dashboard Widget API.

HTTP API

HTTP stands for Hypertext Transfer Protocol and is the foundational communication protocol for the entire Internet. HTTP has several methods, or verbs, that describe particular types of actions. Though a couple more exist, WordPress has pre-built functions for three of the most common. Whenever an HTTP request is made a method is also passed with it to help the server determine what kind of action the client is requesting.

GET

GET is used to retrieve data. This is by far the most commonly used verb. Every time we view a website or pull data from an API we are seeing the result of a GET request.

POST

POST is used to send data to the server for the server to act upon in some way. For example, a contact form. When we enter data into the form fields and click the submit button the browser takes the data and sends a POST request to the server with the text we entered into the form. From there the server will process the contact request.

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:

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

$response      = wp_remote_get( 'https://api.github.com/users/b1ink0' );
$body          = wp_remote_retrieve_body( $response );
$http_code     = wp_remote_retrieve_response_code( $response );
$last_modified = wp_remote_retrieve_header( $response, 'last-modified' );

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.

$body = array(
	'name'    => 'Jane Smith',
	'email'   => 'some@email.com',
	'subject' => 'Checkout this API stuff',
	'comment' => 'I just read a great tutorial. You gotta check it out!',
);

$args = array(
	'body'        => $body,
	'timeout'     => '5',
	'redirection' => '5',
	'httpversion' => '1.0',
	'blocking'    => true,
	'headers'     => array(),
	'cookies'     => array(),
);

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

Transient API

Transients are inherently sped up by caching plugins, where normal Options are not. A memcached plugin, for example, would make WordPress store transient values in fast memory instead of in the database. For this reason, transients should be used to store any data that is expected to expire, or which can expire at any time. Transients should also never be assumed to be in the database, since they may not be stored there at all.

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 us.
$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.

get_transient( $transient );

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

delete_transient( $transient );

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

Dashboard Widget API

wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback, $callback_args );

$widget_id: an identifying slug for our widget. This will be used as its CSS class and its key in the array of widgets.
$widget_name: this is the name our widget will display in its heading.
$callback: The name of a function we will create that will display the actual contents of our widget.
$control_callback (Optional): The name of a function we create that will handle submission of widget options forms and will also display the form elements.
$callback_args (Optional): Set of arguments for the callback function.

/**
 * Add a widget to the dashboard.
 *
 * This function is hooked into the 'wp_dashboard_setup' action below.
 */
function add_dashboard_widgets() {
	wp_add_dashboard_widget(
		'dashboard_widget',                      
		esc_html__( 'Example Dashboard Widget', 'test' ),
		'dashboard_widget_render'                  function.
	); 
}
add_action( 'wp_dashboard_setup', 'wporg_add_dashboard_widgets' );

/**
 * Create the function to output the content of our Dashboard Widget.
 */
function dashboard_widget_render() {
	// Display whatever we want to show.
	esc_html_e( "Howdy! I'm a great Dashboard Widget.", "test" );
}