Most WordPress plugins need to communicate with external services at some point. Whether it’s fetching data from a third-party API, sending notifications to a webhook, or verifying license keys, the WordPress HTTP API provides a standardized way to make HTTP requests. Using the HTTP API instead of raw PHP curl functions ensures compatibility across different hosting environments.
This guide covers how to use the WordPress HTTP API effectively in your plugins.
Making Requests
WordPress provides two functions for making HTTP requests: wp_remote_get() for GET requests and wp_remote_post() for POST requests. Both return a response array containing headers, body, response code, and metadata. Check for errors with is_wp_error() before accessing response data.
Set a reasonable timeout for your requests. The default is 5 seconds, which is appropriate for most use cases. For slow APIs, increase the timeout with the ‘timeout’ parameter. For critical requests, implement retry logic with exponential backoff.
Error Handling
Always check for errors when making HTTP requests. is_wp_error($response) returns true if the request failed due to a network error, timeout, or DNS failure. Check the response code with wp_remote_retrieve_response_code() to handle API-level errors.
Log failed requests for debugging. Store the URL, error message, and timestamp. Implement retry logic for transient failures — network timeouts often succeed on retry. Limit retries to 3 attempts with increasing delays.
Authentication
Many APIs require authentication. Pass authentication credentials in the request headers or body depending on the API’s requirements. For Basic Auth, set the ‘Authorization’ header. For API keys, pass them as a header or query parameter. For OAuth, implement the token exchange flow using wp_remote_post().
Store API credentials securely using the Options API with encrypted values or an external credential store.
Response Handling
Retrieve response components with helper functions: wp_remote_retrieve_body() for the response body, wp_remote_retrieve_header() for specific headers, and wp_remote_retrieve_response_code() for the HTTP status code. Parse the body based on the content type — JSON with json_decode(), XML with simplexml_load_string().
Handle rate limiting by checking the Retry-After header in 429 responses. Cache successful responses with the Transients API to reduce API calls.
Performance
External HTTP requests are slow — typically 200-500ms each. Minimize their impact by caching responses, making requests asynchronously when possible, and combining multiple requests into one. Use the Transients API to cache API responses for an appropriate duration.
For non-critical requests, defer them to a WordPress cron job or wp_remote_post() to your own site for asynchronous processing. This prevents slow external APIs from blocking page loads.
The Bottom Line
The WordPress HTTP API provides a reliable, hosting-compatible way to make external HTTP requests. Always handle errors gracefully, respect API rate limits, cache responses when possible, and keep external requests from blocking page loads. Proper HTTP API usage makes your plugin robust, performant, and compatible across hosting environments.
