From b7afaf7bbd4770282f86221f2bcf0e29776946ed Mon Sep 17 00:00:00 2001 From: Mike Jolley Date: Fri, 13 Oct 2023 16:01:57 +0100 Subject: [PATCH 1/3] Examples and use cases --- .../rest-api/available-endpoints-to-extend.md | 238 +++++++++++++----- 1 file changed, 169 insertions(+), 69 deletions(-) diff --git a/docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md b/docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md index 59a34e2b141..454c7e2d4e4 100644 --- a/docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md +++ b/docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md @@ -2,74 +2,175 @@ ## Table of Contents -- [`wc/store/checkout`](#wcstorecheckout) - - [Passed Parameters](#passed-parameters) - - [Key](#key) -- [`wc/store/cart`](#wcstorecart) - - [Passed Parameters](#passed-parameters-1) - - [Key](#key-1) -- [`wc/store/cart/items`](#wcstorecartitems) - - [Passed Parameters](#passed-parameters-2) - - [Key](#key-2) -- [`wc/store/products`](#wcstoreproducts) - - [Passed Parameters](#passed-parameters-3) - - [Key](#key-3) - -To see how to add your data to Store API using ExtendSchema, [check this document](./extend-rest-api-add-data.md). If you want to add a new endpoint, [check this document](../../../internal-developers/rest-api/extend-rest-api-new-endpoint.md). - -This is a list of available endpoints that you can extend. For other endpoints, [see here](./../../../../src/StoreApi/README.md). - -## `wc/store/checkout` - -The checkout endpoint is extensible via ExtendSchema. The data is available via the `extensions` key in the response. - -### Passed Parameters - -- `data_callback`: none. -- `schema_callback`: none. - -### Key - -- `CheckoutSchema::IDENTIFIER` - -## `wc/store/cart` - -The main cart endpoint is extensible via ExtendSchema. The data is available via the `extensions` key in the response. - -### Passed Parameters - -- `data_callback`: none. -- `schema_callback`: none. - -### Key - -- `CartSchema::IDENTIFIER` - -## `wc/store/cart/items` - -The items endpoint, which is also available on `wc/store/cart` inside the `items` key. The data would be available inside each item of the `items` array. - -### Passed Parameters - -- `data_callback`: `$cart_item`. -- `schema_callback` none. - -### Key - -- `CartItemSchema::IDENTIFIER` - -## `wc/store/products` - -The main products endpoint is extensible via ExtendSchema. The data is available via the `extensions` key for each `product` in the response array. - -### Passed Parameters - -- `data_callback`: `$product`. -- `schema_callback` none. - -### Key - -- `ProductSchema::IDENTIFIER` +- [Checkout](#checkout) + - [Use Cases](#use-cases) + - [Example](#example) +- [Cart](#cart) + - [Use Cases](#use-cases-1) + - [Example](#example-1) +- [Cart Items](#cart-items) + - [Use Cases](#use-cases-2) + - [Example](#example-2) +- [Products](#products) + - [Use Cases](#use-cases-3) + - [Example](#example-3) + +Some endpoints of the Store API are extensible via a class called `ExtendSchema`. This allows you to customise the data (including the schema) that is returned by the Store API so that it can be consumed by your application or plugin. + +For more information about extending the Store API, you may also be interested in: + +- [The full list of available endpoints, including those that cannot currently be extended](../../../internal-developers/rest-api/extend-rest-api.md) +- [How to add your data to Store API using `ExtendSchema`](./extend-rest-api-add-data.md) +- [How to add a new endpoint](../../../internal-developers/rest-api/extend-rest-api-new-endpoint.md) + +Below is a list of available endpoints that you can extend using `ExtendSchema`, as well as some example use-cases. + +## Checkout + +The `wc/store/checkout` endpoint is extensible via ExtendSchema. Additional data is available via the `extensions` key in the response. + +This endpoint can be extended using the `CheckoutSchema::IDENTIFIER` key. For this endpoint, your `data_callback` and `schema_callback` functions are passed no additional parameters. + +### Use Cases + +This endpoint is useful for adding additional data to the checkout page, such as a custom payment method which requires additional data to be collected from the user or server. + +Important: Do **not** reveal any sensitive data in this endpoint, as it is publicly accessible. This includes private keys for payment services. + +### Example + +```php +woocommerce_store_api_register_endpoint_data( + array( + 'endpoint' => CheckoutSchema::IDENTIFIER, + 'namespace' => 'my_plugin_namespace', + 'data_callback' => function() { + return array( + 'foo' => 'bar', + ); + }, + 'schema_callback' => function() { + return array( + 'properties' => array( + 'foo' => array( + 'type' => 'string', + ), + ), + ); + } + 'schema_type' => ARRAY_A, + ) +); +``` + +## Cart + +The main `wc/store/cart` endpoint is extensible via ExtendSchema. The data is available via the `extensions` key in the response. + +This endpoint can be extended using the `CartSchema::IDENTIFIER` key. For this endpoint, your `data_callback` and `schema_callback` functions are passed no additional parameters. + +### Use Cases + +This endpoint is useful for adding additional data to the cart page, for example, extra data about the cart items, or anything else needed to support custom blocks displayed on the cart page. + +### Example + +```php +woocommerce_store_api_register_endpoint_data( + array( + 'endpoint' => CartSchema::IDENTIFIER, + 'namespace' => 'my_plugin_namespace', + 'data_callback' => function() { + return array( + 'foo' => 'bar', + ); + }, + 'schema_callback' => function() { + return array( + 'properties' => array( + 'foo' => array( + 'type' => 'string', + ), + ), + ); + } + 'schema_type' => ARRAY_A, + ) +); +``` + +## Cart Items + +The `wc/store/cart/items` endpoint, which is also available on `wc/store/cart` inside the `items` key. The data would be available inside each item of the `items` array. + +This endpoint can be extended using the `CartItemSchema::IDENTIFIER` key. For this endpoint, your `data_callback` callback function is passed `$cart_item` as a parameter. Your `schema_callback` function is passed no additional parameters; all cart items should share the same schema. + +### Use Cases + +This endpoint is useful for adding additional data about individual cart items. This could be some meta data, additional pricing, or anything else to support custom blocks or components on the cart page. + +### Example + +```php +woocommerce_store_api_register_endpoint_data( + array( + 'endpoint' => CartItemSchema::IDENTIFIER, + 'namespace' => 'my_plugin_namespace', + 'data_callback' => function( $cart_item ) { + $product = $cart_item['data']; + return array( + 'my_meta_data' => get_post_meta( $product->get_id(), 'my_meta_data', true ), + ); + }, + 'schema_callback' => function() { + return array( + 'properties' => array( + 'my_meta_data' => array( + 'type' => 'string', + ), + ), + ); + } + 'schema_type' => ARRAY_A, + ) +); +``` + +## Products + +The main `wc/store/products` endpoint is extensible via ExtendSchema. The data is available via the `extensions` key for each `product` in the response array. + +This endpoint can be extended using the `ProductSchema::IDENTIFIER` key. For this endpoint, your `data_callback` callback function is passed `$product` as a parameter. Your `schema_callback` function is passed no additional parameters; all products should share the same schema. + +### Use Cases + +This endpoint is useful for adding additional data about individual products. This could be some meta data, additional pricing, or anything else to support custom blocks or components on the products page. + +### Example + +```php +woocommerce_store_api_register_endpoint_data( + array( + 'endpoint' => ProductSchema::IDENTIFIER, + 'namespace' => 'my_plugin_namespace', + 'data_callback' => function( $product ) { + return array( + 'my_meta_data' => get_post_meta( $product->get_id(), 'my_meta_data', true ), + ); + }, + 'schema_callback' => function() { + return array( + 'properties' => array( + 'my_meta_data' => array( + 'type' => 'string', + ), + ), + ); + } + 'schema_type' => ARRAY_A, + ) +); +``` @@ -80,4 +181,3 @@ The main products endpoint is extensible via ExtendSchema. The data is available 🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md) - From 45a2a9e6ae0542603d31cfa501441738fd4ca40e Mon Sep 17 00:00:00 2001 From: Mike Jolley Date: Mon, 16 Oct 2023 11:30:43 +0100 Subject: [PATCH 2/3] Address feedback --- .../rest-api/available-endpoints-to-extend.md | 73 +++++++++---------- woocommerce-gutenberg-products-block.php | 22 ++++++ 2 files changed, 58 insertions(+), 37 deletions(-) diff --git a/docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md b/docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md index 454c7e2d4e4..07abc12986b 100644 --- a/docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md +++ b/docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md @@ -2,7 +2,7 @@ ## Table of Contents -- [Checkout](#checkout) +- [Products](#products) - [Use Cases](#use-cases) - [Example](#example) - [Cart](#cart) @@ -11,7 +11,7 @@ - [Cart Items](#cart-items) - [Use Cases](#use-cases-2) - [Example](#example-2) -- [Products](#products) +- [Checkout](#checkout) - [Use Cases](#use-cases-3) - [Example](#example-3) @@ -19,46 +19,43 @@ Some endpoints of the Store API are extensible via a class called `ExtendSchema` For more information about extending the Store API, you may also be interested in: -- [The full list of available endpoints, including those that cannot currently be extended](../../../internal-developers/rest-api/extend-rest-api.md) - [How to add your data to Store API using `ExtendSchema`](./extend-rest-api-add-data.md) - [How to add a new endpoint](../../../internal-developers/rest-api/extend-rest-api-new-endpoint.md) Below is a list of available endpoints that you can extend using `ExtendSchema`, as well as some example use-cases. -## Checkout +## Products -The `wc/store/checkout` endpoint is extensible via ExtendSchema. Additional data is available via the `extensions` key in the response. +The main `wc/store/products` endpoint is extensible via ExtendSchema. The data is available via the `extensions` key for each `product` in the response array. -This endpoint can be extended using the `CheckoutSchema::IDENTIFIER` key. For this endpoint, your `data_callback` and `schema_callback` functions are passed no additional parameters. +This endpoint can be extended using the `ProductSchema::IDENTIFIER` key. For this endpoint, your `data_callback` callback function is passed `$product` as a parameter. Your `schema_callback` function is passed no additional parameters; all products should share the same schema. ### Use Cases -This endpoint is useful for adding additional data to the checkout page, such as a custom payment method which requires additional data to be collected from the user or server. - -Important: Do **not** reveal any sensitive data in this endpoint, as it is publicly accessible. This includes private keys for payment services. +This endpoint is useful for adding additional data about individual products. This could be some meta data, additional pricing, or anything else to support custom blocks or components on the products page. ### Example ```php woocommerce_store_api_register_endpoint_data( array( - 'endpoint' => CheckoutSchema::IDENTIFIER, - 'namespace' => 'my_plugin_namespace', - 'data_callback' => function() { + 'endpoint' => ProductSchema::IDENTIFIER, + 'namespace' => 'my_plugin_namespace', + 'data_callback' => function( $product ) { return array( - 'foo' => 'bar', + 'my_meta_data' => get_post_meta( $product->get_id(), 'my_meta_data', true ), ); }, 'schema_callback' => function() { return array( 'properties' => array( - 'foo' => array( + 'my_meta_data' => array( 'type' => 'string', ), ), ); - } - 'schema_type' => ARRAY_A, + }, + 'schema_type' => ARRAY_A, ) ); ``` @@ -78,9 +75,9 @@ This endpoint is useful for adding additional data to the cart page, for example ```php woocommerce_store_api_register_endpoint_data( array( - 'endpoint' => CartSchema::IDENTIFIER, - 'namespace' => 'my_plugin_namespace', - 'data_callback' => function() { + 'endpoint' => CartSchema::IDENTIFIER, + 'namespace' => 'my_plugin_namespace', + 'data_callback' => function() { return array( 'foo' => 'bar', ); @@ -93,8 +90,8 @@ woocommerce_store_api_register_endpoint_data( ), ), ); - } - 'schema_type' => ARRAY_A, + }, + 'schema_type' => ARRAY_A, ) ); ``` @@ -114,9 +111,9 @@ This endpoint is useful for adding additional data about individual cart items. ```php woocommerce_store_api_register_endpoint_data( array( - 'endpoint' => CartItemSchema::IDENTIFIER, - 'namespace' => 'my_plugin_namespace', - 'data_callback' => function( $cart_item ) { + 'endpoint' => CartItemSchema::IDENTIFIER, + 'namespace' => 'my_plugin_namespace', + 'data_callback' => function( $cart_item ) { $product = $cart_item['data']; return array( 'my_meta_data' => get_post_meta( $product->get_id(), 'my_meta_data', true ), @@ -130,44 +127,46 @@ woocommerce_store_api_register_endpoint_data( ), ), ); - } - 'schema_type' => ARRAY_A, + }, + 'schema_type' => ARRAY_A, ) ); ``` -## Products +## Checkout -The main `wc/store/products` endpoint is extensible via ExtendSchema. The data is available via the `extensions` key for each `product` in the response array. +The `wc/store/checkout` endpoint is extensible via ExtendSchema. Additional data is available via the `extensions` key in the response. -This endpoint can be extended using the `ProductSchema::IDENTIFIER` key. For this endpoint, your `data_callback` callback function is passed `$product` as a parameter. Your `schema_callback` function is passed no additional parameters; all products should share the same schema. +This endpoint can be extended using the `CheckoutSchema::IDENTIFIER` key. For this endpoint, your `data_callback` and `schema_callback` functions are passed no additional parameters. ### Use Cases -This endpoint is useful for adding additional data about individual products. This could be some meta data, additional pricing, or anything else to support custom blocks or components on the products page. +This endpoint is useful for adding additional data to the checkout page, such as a custom payment method which requires additional data to be collected from the user or server. + +⚠ **Important: Do **not** reveal any sensitive data in this endpoint, as it is publicly accessible. This includes private keys for payment services.** ### Example ```php woocommerce_store_api_register_endpoint_data( array( - 'endpoint' => ProductSchema::IDENTIFIER, - 'namespace' => 'my_plugin_namespace', - 'data_callback' => function( $product ) { + 'endpoint' => CheckoutSchema::IDENTIFIER, + 'namespace' => 'my_plugin_namespace', + 'data_callback' => function() { return array( - 'my_meta_data' => get_post_meta( $product->get_id(), 'my_meta_data', true ), + 'foo' => 'bar', ); }, 'schema_callback' => function() { return array( 'properties' => array( - 'my_meta_data' => array( + 'foo' => array( 'type' => 'string', ), ), ); - } - 'schema_type' => ARRAY_A, + }, + 'schema_type' => ARRAY_A, ) ); ``` diff --git a/woocommerce-gutenberg-products-block.php b/woocommerce-gutenberg-products-block.php index c83b8e47a81..3691babfcef 100644 --- a/woocommerce-gutenberg-products-block.php +++ b/woocommerce-gutenberg-products-block.php @@ -18,6 +18,28 @@ defined( 'ABSPATH' ) || exit; +woocommerce_store_api_register_endpoint_data( + array( + 'endpoint' => ProductSchema::IDENTIFIER, + 'namespace' => 'my_plugin_namespace', + 'data_callback' => function( $product ) { + return array( + 'my_meta_data' => get_post_meta( $product->get_id(), 'my_meta_data', true ), + ); + }, + 'schema_callback' => function() { + return array( + 'properties' => array( + 'my_meta_data' => array( + 'type' => 'string', + ), + ), + ); + }, + 'schema_type' => ARRAY_A, + ) +); + $minimum_wp_version = '6.3'; if ( ! defined( 'WC_BLOCKS_IS_FEATURE_PLUGIN' ) ) { From 03a556ee4275b77af7f99e5dceb157dc6f0d3ea8 Mon Sep 17 00:00:00 2001 From: Mike Jolley Date: Mon, 16 Oct 2023 11:31:26 +0100 Subject: [PATCH 3/3] Revert addition to main file --- woocommerce-gutenberg-products-block.php | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/woocommerce-gutenberg-products-block.php b/woocommerce-gutenberg-products-block.php index 3691babfcef..c83b8e47a81 100644 --- a/woocommerce-gutenberg-products-block.php +++ b/woocommerce-gutenberg-products-block.php @@ -18,28 +18,6 @@ defined( 'ABSPATH' ) || exit; -woocommerce_store_api_register_endpoint_data( - array( - 'endpoint' => ProductSchema::IDENTIFIER, - 'namespace' => 'my_plugin_namespace', - 'data_callback' => function( $product ) { - return array( - 'my_meta_data' => get_post_meta( $product->get_id(), 'my_meta_data', true ), - ); - }, - 'schema_callback' => function() { - return array( - 'properties' => array( - 'my_meta_data' => array( - 'type' => 'string', - ), - ), - ); - }, - 'schema_type' => ARRAY_A, - ) -); - $minimum_wp_version = '6.3'; if ( ! defined( 'WC_BLOCKS_IS_FEATURE_PLUGIN' ) ) {