Best Practices For Calling External Apis From WordPress Plugins And Themes
Connecting to External APIs
Connecting to external APIs allows WordPress plugins and themes to incorporate dynamic, up-to-date content from other web services. For example, a plugin might connect to a weather API to display forecasts, while a theme pulls in latest tweets or Instagram photos through social media APIs.
When integrating WordPress with external APIs, developers need to make decisions around choosing the right API integration method, handling API requests and responses, authenticating with OAuth if necessary, caching API responses to conserve quotas, monitoring API connections, and properly troubleshooting issues.
Choosing the Right API Integration Method
The WordPress platform offers multiple methods for integrating with external APIs:
- The built-in HTTP API in WordPress core
- Server-side plugins like Jetpack or Pods Framework
- Custom PHP code in a plugin or theme
- JavaScript calls from front-end code
Factors to consider when selecting an integration method:
- API data usage – Will it be used only on the front-end or also on admin screens and in templates?
- Required interaction – Does the API need to connect server-side or can it run client-side?
- Integration complexity – Server-side offers more logic but client-side is faster.
- Performance overhead – Adding more server-side calls can slow down page loading.
- Security implications – Server-side is more secure for handling API keys.
For simple front-end API usage, client-side JavaScript integration offers a fast way with minimal coding. But for complex integrations or server-side usage, a custom PHP plugin tailored specifically for that API may be the best approach.
Handling API Requests and Responses
Once an integration method is selected, the plugin/theme code needs to properly handle API requests and process returned responses:
- Construct a well-formed API request URL – Encode parameters correctly
- Set API version (v1, v2) in endpoint URL for versioning
- Make request using WordPress HTTP API or JavaScript Fetch
- Check response status codes (200 OK, 404 Not Found, etc)
- Decode JSON response body with json_decode() or JavaScript
- Handle errors gracefully and fall back to defaults
Use try/catch blocks and check return values from each API call. Log errors to the PHP error log or browser developer console for troubleshooting issues.
For improved performance, make API requests asynchronously without blocking page loading, if possible. In JavaScript, use promises or async/await syntax. For PHP, look into curl_multi or background processing with cron.
Authenticating with OAuth
Many web APIs now use the OAuth standard to handle secure authentication and authorization:
- Allows access tokens instead of usernames/passwords
- Tokens grant limited access to API without exposing user credentials
- Create app credentials within API provider portal
- Registration involves getting consumer key & secret
- Use library like WordPress OAuth Client plugin to abstract process
The OAuth authentication flow involves multiple steps:
- Redirect user to provider login screen to grant access
- User authorizes app through consent screen
- Provider issues access token string
- Token gets stored server-side or client-side
- Token passed in API requests as authorization
- Refresh token periodically before expiration
OAuth improves security since actual app credentials are not exposed. Users can also revoke app authorization. Implement OAuth authentication properly before integrating WordPress with restricted APIs.
Caching API Responses
Live API requests can strain connection quotas and affect performance:
- Many APIs enforce hourly limits
- Caching responses avoids hitting quotas
- Creates snappier user experience
- Store cache as WordPress transients
- Only re-fetch data when cache expires
- If quota met, fall back to last cached API response
Effective caching strategies:
- Cache endpoint responses separately in keys by endpoint
- Set cache expiration to <60% of quota refresh time
- For public READ APIs, can use longer expirations
- Version the transient keys by date or API version
Relying solely on live API connections risks quota failures. Implement response caching to optimize quotas and performance.
Monitoring and Troubleshooting API Connections
With external service integrations, API issues can disrupt WordPress site behavior:
- Transient errors and network flakes
- Rate limits causing failures
- Changes to API specifications
- Service outages at API provider
Plan to monitor API connectivity and troubleshoot problems:
- Crucial to have error handling in integration code
- Log API response codes to detect errors
- Inspect browser network tab or PHP logs
- Monitor overall site performance for anomalies
- Set up uptime monitoring to receive alerts
- Before deploying, load test APIs to quantify limits
Monitoring and quick error notifications let developers identify and respond promptly to API issues experienced on production sites.
Example Code for Calling an API
Here is PHP code demonstrating a simple pattern for calling an external API from WordPress:
/**
* Gets places nearby the given GPS coordinates from Places API.
*
* Returns array of place data.
*/
function get_nearby_places( $lat, $lon ) {
// API base URL
$base_url = 'https://api.example.com/v1/places';
// Parameters
$params = array(
'lat' => $lat,
'lon' => $lon,
'radius' => 5000, // 5KM
'types' => 'restaurant,lodging',
'key' => API_KEY
);
// Call API and decode response
$response = wp_remote_get( $base_url, array(
'timeout' => 60,
'headers' => array('Accept' => 'application/json'),
'query_params' => $params
) );
if( is_wp_error($response) ) {
return array();
}
$places = json_decode( wp_remote_retrieve_body( $response ) );
return $places;
}
This demonstrates core aspects like constructing API URL with parameters, making wp_remote_get() call, handling errors, and decoding JSON response.
Similarly, JavaScript code can use the Fetch API and process promises for calling APIs client-side.
