External API Developers Guide
Learn how to extend Cornerstone's External API and incorparate any data into WordPress.
Extending
All Extension API functions and filters are prefixed cs_api_. To avoid confusion, when this doc refers to the a API it is referring to the Extension API and the Cornerstone API is considered anything prefixed with cs_.
These functions and the API are not included unless the option cs_api_extension_enabled is true and you need to check this if you are using any of these functions.
Custom Global Endpoint
Use these examples to create a plugin or child theme that has a Global Endpoint managed by code and not the UI. This can be helpful for sharing External APIs between different sites or you create an External API and wish to get your product on CS through a plugin.
The following is an example of adding a Custom Global Endpoint called "PokeAPI Global".
// Add global api endpoint
add_filter("cs_api_global_endpoints", function($endpoints) {
// Add to global list
$endpoints[] = [
'id' => 'pokeapi',
'name' => __('PokeAPI Global'),
'endpoint' => 'https://pokeapi.co/api/v2/',
'method' => 'GET',
];
return $endpoints;
});Values in a Global Endpoint
These values are named the same as the looper provider values for easier merging. The following values are also the default values
namespace Themeco\Cornerstone\API;
const BUILTIN_VALUES = [
'endpoint' => '',
'path' => '',
'method' => 'GET',
'headers' => '',
'cache_time' => '',
'request_type' => 'attributes',
'args' => '',
'return_type' => 'json',
'data_key' => '',
'timeout' => 7,
'httpconnect_timeout' => 7,
'debug' => false,
];Custom Request Type
Request type editors can be added through the function cs_api_register_request_type. If your request type does not return a string, it will be auto converted to JSON to send to the endpoint.
cs_api_register_request_type($type, $args = [])
@param string $type
Type name, needs to be unique. Prefer - over _ as it makes the dev tools easier to read since it prefixes the values with a _.
@param array $args
label | ✔ | string | Localized title to display under the stack selector. |
controls | array | Using Cornerstones Element API to build out controls or a function that returns an array. | |
values | array | Associative array which saves value data used in controls. | |
request_filter | callable | Function to use to filter request data into a request the server is expecting. | |
| Key | Required | Type | Description |
|---|
// Register our request editor type 'example'
cs_api_register_request_type("example", [
// Localized label
'label' => __("Example", "cornerstone"),
// Values to store in looper provider data
'values' => [
'test' => true,
],
// Controls when this request type editor is in place
'controls' => [
// Test Control Toggle
[
'key' => 'test',
'label' => __("Test", "cornerstone"),
'type' => 'toggle',
],
],
// Filter to use before sending endpoint
'request_filter' => function($body, $type, $args) {
// Using our control values from earlier
if (empty($data['test'])) {
return [];
}
// Since this is an array it will be autoconverted to JSON
// Send a string here instead to disregard that encoding
return [
'mydata' => true,
];
},
]);Custom Return Type
Return types can be added through the function cs_api_register_return_type. See the Looper API for info on how this data is stored internally.
cs_api_register_return_type($type, $args = [])
@param string $type
Type name, needs to be unique. Prefer - over _ as it makes the dev tools easier to read since it prefixes the values with a _.
@param array $args
label | ✔ | string | Localized title to display under the stack selector. |
controls | array | Using Cornerstones Element API to build out controls or a function that returns an array. | |
values | array | Associative array which saves value data used in controls. | |
filter | callable | Function to use to filter response data into an array. | |
| Key | Required | Type | Description |
|---|
The following is a sample grabbed from the YAML return type.
// Register custom return type
cs_api_register_return_type("yaml", [
'label' => __("Yaml", "cornerstone"),
'filter' => function($result, $args = []) {
return yaml_parse($result);
},
]);All Extending Functions
Below is a full list of the functions offered by the External API
/**
* Filter a return passed from an endpoint
* Use extensions and a filter named the same
*
* @param string $result
* @param string $type
* @param array $args
*
* @return mixed
*/
function cs_api_filter_return($result, $type, $args = []);
/**
* Identical to cs_api_filter_return accept this
* sends its return to the endpoint
* uses extensions and a filter named the same
*
* @param string $result
* @param string $type
* @param array $args
*
* @return mixed
*/
function cs_api_filter_request($result, $type, $args = []);
/**
* Values used by api extensions
* both return and request extensions values
* are present in this associative array
*
* @return array
*/
function cs_api_extension_values();
/**
* Using an endpoint and args grab a cache file
*
* @param string $endpoint
* @param array $args
*
* @return string
*/
function cs_api_get_cache($endpoint, $args);
/**
* Does this current file match the cache time requirements
*
* @param string $filePath
* @param array $args
*
* @return boolean
*/
function cs_api_file_passes_cache($filePath, $args = []);
/**
* Check internal allow list on endpoint
*
* @param string $endpoint
*
* @return bool
*/
function cs_api_check_allowlist($endpoint);
/**
* Save curl cache from endpoint and args
*/
function cs_api_set_cache($endpoint, $args = [], $content = '');
/**
* Grab data from endpoint from cache
*/
function cs_api_cache_file($endpoint, $args);
/**
* Main register function for return type extensions
*
* @param string $type
* @param array $config
*
* @return void
*/
function cs_api_register_return_type($type, $config = []);
/**
* Gets return types registered
*
* @return array
*/
function cs_api_return_types();
/**
* An array of { value, label } objects
* useable in CS select and choose controls
*
* @return array
*/
function cs_api_return_types_as_choices();
/**
* Selector and controls for return type extensions
*
* @return array
*/
function cs_api_return_type_controls();
/**
* Main register function for a API request type extension
*
* @param string $type
* @param array $config
*
* @return void
*/
function cs_api_register_request_type($type, $config);
/**
* Selector and controls for request type extensions
*
* @return array
*/
function cs_api_request_type_controls();
/**
* Get all Global endpoints
* uses a filter by the same name
*
* @return array
*/
function cs_api_global_endpoints();
/**
* Get endpoint by ID
*
* @param string $id
*
* @return array|null
*/
function cs_api_global_endpoint($id);
/**
* Main runner from DC or looper data to either
* cache grab or makes curl request
*
* @param array args
*
* @return mixed
*/
function cs_api_run($args = []);
/**
* Using global_id as an arg merge with other arguments
*
* @param array $args
*
* @return mixed
*/
function cs_api_global_run($args = []);
/**
* Merge key if likewise array values
*
* @param array $args
* @param array $endpoint
* @param string $key
*
* @return array
*/
function cs_api_global_merge_with_args($args, $endpoint, $key);Cache Functions
/**
* Using an endpoint and args grab a cache file
*
* @param string $endpoint
* @param array $args
*
* @return string
*/
function cs_api_get_cache($endpoint, $args);
/**
* Save curl cache from endpoint and args
*
* @param string $endpoint
* @param array $args
* @param string $content
*
* @return int|false
*/
function cs_api_set_cache($endpoint, $args = [], $content = '');
/**
* Cache file create name
*
* @param string $endpoint
* @param array $args
*/
function cs_api_cache_file($endpoint, $args = []);
/**
* Get External API Cache directory
*
* @return string
*/
function cs_api_cache_directory();See something inaccurate? Let us know