Steve-Dee-Designs
/
woocommerce
mirror of https://github.com/woocommerce/woocommerce.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
woocommerce/plugins/woocommerce-blocks/src/StoreApi/README.md

105 lines
8.1 KiB
Markdown
Raw Normal View History

Introduce a Cart API on top of the REST API (https://github.com/woocommerce/woocommerce-blocks/pull/1046) * Cart add endpoint and schema * Empty card DELETE method * Merge into single controller * Revise verb usage * PUT/update requests * Move under rest api namespace * Basic test coverage * Invalid tests with status check * Variation handling * Update src/RestApi/StoreApi/Schemas/CartItemSchema.php Co-Authored-By: Albert Juhé Lluveras <contact@albertjuhe.com> * Remove key arg for delete endpoint * code comment for creation * rename param to product_id * Renaming methods from _item to _cart_item
2019-10-21 11:11:52 +00:00
# WooCommerce Store API
Documentation for the Store API (https://github.com/woocommerce/woocommerce-blocks/pull/2230) * Products endpoint * Updated STORE API docs * Enable nonce protection for checkout endpoints and document * feedback
2020-04-17 09:44:13 +00:00
The WooCommerce Store API is a public-facing (for internal use only currently) REST API. Unlike the main WooCommerce REST API, this API does not require authentication and is intended to be used by customer facing client side code.
Introduce a Cart API on top of the REST API (https://github.com/woocommerce/woocommerce-blocks/pull/1046) * Cart add endpoint and schema * Empty card DELETE method * Merge into single controller * Revise verb usage * PUT/update requests * Move under rest api namespace * Basic test coverage * Invalid tests with status check * Variation handling * Update src/RestApi/StoreApi/Schemas/CartItemSchema.php Co-Authored-By: Albert Juhé Lluveras <contact@albertjuhe.com> * Remove key arg for delete endpoint * code comment for creation * rename param to product_id * Renaming methods from _item to _cart_item
2019-10-21 11:11:52 +00:00
Documentation for the Store API (https://github.com/woocommerce/woocommerce-blocks/pull/2230) * Products endpoint * Updated STORE API docs * Enable nonce protection for checkout endpoints and document * feedback
2020-04-17 09:44:13 +00:00
This documentation assumes knowledge of REST concepts.
Introduce a Cart API on top of the REST API (https://github.com/woocommerce/woocommerce-blocks/pull/1046) * Cart add endpoint and schema * Empty card DELETE method * Merge into single controller * Revise verb usage * PUT/update requests * Move under rest api namespace * Basic test coverage * Invalid tests with status check * Variation handling * Update src/RestApi/StoreApi/Schemas/CartItemSchema.php Co-Authored-By: Albert Juhé Lluveras <contact@albertjuhe.com> * Remove key arg for delete endpoint * code comment for creation * rename param to product_id * Renaming methods from _item to _cart_item
2019-10-21 11:11:52 +00:00
REST API - Store API - Product filtering data, products endpoint, and cart refinements (https://github.com/woocommerce/woocommerce-blocks/pull/1055) * Cart add endpoint and schema * Empty card DELETE method * Merge into single controller * Revise verb usage * PUT/update requests * Move under rest api namespace * Basic test coverage * Invalid tests with status check * Variation handling * Update src/RestApi/StoreApi/Schemas/CartItemSchema.php Co-Authored-By: Albert Juhé Lluveras <contact@albertjuhe.com> * Remove key arg for delete endpoint * code comment for creation * rename param to product_id * Renaming methods from _item to _cart_item * Prepare storeAPI products endpoint for public use * Price filter headers * Attribute counts * Add Rating filter * Rating counts * Fix counts * Moved utilities * API docs * Use correct response for cart item * Attributes filtering * Stats * Products/Stats unit tests * Rename stats to collection data * Remove `embed` from schema * Add since $VID:$ tags * Improve operator logic and add isset checks * Force cart schema to be readonly
2019-10-25 09:43:52 +00:00
## Current status
Introduce a Cart API on top of the REST API (https://github.com/woocommerce/woocommerce-blocks/pull/1046) * Cart add endpoint and schema * Empty card DELETE method * Merge into single controller * Revise verb usage * PUT/update requests * Move under rest api namespace * Basic test coverage * Invalid tests with status check * Variation handling * Update src/RestApi/StoreApi/Schemas/CartItemSchema.php Co-Authored-By: Albert Juhé Lluveras <contact@albertjuhe.com> * Remove key arg for delete endpoint * code comment for creation * rename param to product_id * Renaming methods from _item to _cart_item
2019-10-21 11:11:52 +00:00
Documentation for the Store API (https://github.com/woocommerce/woocommerce-blocks/pull/2230) * Products endpoint * Updated STORE API docs * Enable nonce protection for checkout endpoints and document * feedback
2020-04-17 09:44:13 +00:00
This API is used internally by Blocks--it is still in flux and may be subject to revisions. There is currently no versioning system, and this API should therefore be used at your own risk. Eventually, it will be moved to the main WooCommerce REST API at which point it will be versioned and safe to use in other projects.
REST API - Store API - Product filtering data, products endpoint, and cart refinements (https://github.com/woocommerce/woocommerce-blocks/pull/1055) * Cart add endpoint and schema * Empty card DELETE method * Merge into single controller * Revise verb usage * PUT/update requests * Move under rest api namespace * Basic test coverage * Invalid tests with status check * Variation handling * Update src/RestApi/StoreApi/Schemas/CartItemSchema.php Co-Authored-By: Albert Juhé Lluveras <contact@albertjuhe.com> * Remove key arg for delete endpoint * code comment for creation * rename param to product_id * Renaming methods from _item to _cart_item * Prepare storeAPI products endpoint for public use * Price filter headers * Attribute counts * Add Rating filter * Rating counts * Fix counts * Moved utilities * API docs * Use correct response for cart item * Attributes filtering * Stats * Products/Stats unit tests * Rename stats to collection data * Remove `embed` from schema * Add since $VID:$ tags * Improve operator logic and add isset checks * Force cart schema to be readonly
2019-10-25 09:43:52 +00:00
## Basic usage
Example of a valid API request using cURL:
```http
curl "https://example-store.com/wp-json/wc/store/products"
```
The API uses JSON to serialize data. You don’t need to specify `.json` at the end of an API URL.
## Namespace
Resources in the Store API are all found within the `wc/store/` namespace, and since this API extends the WordPress API, accessing it requires the `/wp-json/` base. Examples:
```http
GET /wp-json/wc/store/products
GET /wp-json/wc/store/cart
```
## Authentication
Documentation for the Store API (https://github.com/woocommerce/woocommerce-blocks/pull/2230) * Products endpoint * Updated STORE API docs * Enable nonce protection for checkout endpoints and document * feedback
2020-04-17 09:44:13 +00:00
Requests to the store API do not require authentication. Only public data is returned, and most endpoints are read-only, with the exception of the cart API which only lets you manipulate data for the current session, and requires a [nonce token](https://developer.wordpress.org/plugins/security/nonces/).
REST API - Store API - Product filtering data, products endpoint, and cart refinements (https://github.com/woocommerce/woocommerce-blocks/pull/1055) * Cart add endpoint and schema * Empty card DELETE method * Merge into single controller * Revise verb usage * PUT/update requests * Move under rest api namespace * Basic test coverage * Invalid tests with status check * Variation handling * Update src/RestApi/StoreApi/Schemas/CartItemSchema.php Co-Authored-By: Albert Juhé Lluveras <contact@albertjuhe.com> * Remove key arg for delete endpoint * code comment for creation * rename param to product_id * Renaming methods from _item to _cart_item * Prepare storeAPI products endpoint for public use * Price filter headers * Attribute counts * Add Rating filter * Rating counts * Fix counts * Moved utilities * API docs * Use correct response for cart item * Attributes filtering * Stats * Products/Stats unit tests * Rename stats to collection data * Remove `embed` from schema * Add since $VID:$ tags * Improve operator logic and add isset checks * Force cart schema to be readonly
2019-10-25 09:43:52 +00:00
## Status codes
The following table gives an overview of how the API functions generally behave.
| Request type | Description |
| :----------- | :---------------------------------------------------------------------------------------------------------- |
| `GET` | Access one or more resources and return `200 OK` and the result as JSON. |
| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
| `PUT` | Return `200 OK` if the resource is modified successfully. The modified result is returned as JSON. |
| `DELETE` | Returns `204 No Content` if the resource was deleted successfully. |
The following table shows the possible return codes for API requests.
Documentation for the Store API (https://github.com/woocommerce/woocommerce-blocks/pull/2230) * Products endpoint * Updated STORE API docs * Enable nonce protection for checkout endpoints and document * feedback
2020-04-17 09:44:13 +00:00
| Response code | Description |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `200 OK` | The request was successful, the resource(s) itself is returned as JSON. |
| `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
| `201 Created` | The POST request was successful and the resource is returned as JSON. |
| `400 Bad Request` | A required attribute of the API request is missing. | |
| `403 Forbidden` | The request is not allowed. |
| `404 Not Found` | A resource could not be accessed, for example it doesn't exist. |
| `405 Method Not Allowed` | The request is not supported. |
| `409 Conflict` | The request could not be completed due to a conflict with the current state of the target resource. The current state may also be returned. |
| `500 Server Error` | While handling the request something went wrong server-side. |
REST API - Store API - Product filtering data, products endpoint, and cart refinements (https://github.com/woocommerce/woocommerce-blocks/pull/1055) * Cart add endpoint and schema * Empty card DELETE method * Merge into single controller * Revise verb usage * PUT/update requests * Move under rest api namespace * Basic test coverage * Invalid tests with status check * Variation handling * Update src/RestApi/StoreApi/Schemas/CartItemSchema.php Co-Authored-By: Albert Juhé Lluveras <contact@albertjuhe.com> * Remove key arg for delete endpoint * code comment for creation * rename param to product_id * Renaming methods from _item to _cart_item * Prepare storeAPI products endpoint for public use * Price filter headers * Attribute counts * Add Rating filter * Rating counts * Fix counts * Moved utilities * API docs * Use correct response for cart item * Attributes filtering * Stats * Products/Stats unit tests * Rename stats to collection data * Remove `embed` from schema * Add since $VID:$ tags * Improve operator logic and add isset checks * Force cart schema to be readonly
2019-10-25 09:43:52 +00:00
## Pagination
If collections contain many results, they may be paginated. When listing resources you can pass the following parameters:
| Parameter | Description |
| :--------- | :------------------------------------------------------------------------------------- |
| `page` | Current page of the collection. Defaults to `1`. |
| `per_page` | Maximum number of items to be returned in result set. Defaults to `10`. Maximum `100`. |
In the example below, we list 20 products per page and return page 2.
```http
curl "https://example-store.com/wp-json/wc/store/products?page=2&per_page=20"
```
### Pagination headers
Additional pagination headers are also sent back.
| Header | Description |
| :---------------- | :------------------------------------------------------------------------ |
| `X-WP-Total` | The total number of items in the collection. |
| `X-WP-TotalPages` | The total number of pages in the collection. |
| `Link` | Contains links to other pages; `next`, `prev`, and `up` where applicable. |
Documentation for the Store API (https://github.com/woocommerce/woocommerce-blocks/pull/2230) * Products endpoint * Updated STORE API docs * Enable nonce protection for checkout endpoints and document * feedback
2020-04-17 09:44:13 +00:00
## API resources and endpoints
Available resources in the Store API are listed below, with links to more detailed documentation.
| Resource | Available endpoints |
| :----------------------------------------------------------- | :------------------------------------------------------------------------------------ |
| [`Cart`](docs/cart.md) | [`/wc/store/cart`](docs/cart.md#get-cart) |
| | [`/wc/store/cart/add-item`](#add-item) |
| | [`/wc/store/cart/remove-item`](#remove-item) |
| | [`/wc/store/cart/update-item`](#update-item) |
| | [`/wc/store/cart/apply-coupon`](#apply-coupon) |
| | [`/wc/store/cart/remove-coupon`](#remove-coupon) |
Sync shipping address with billing address when shipping address fields are disabled (https://github.com/woocommerce/woocommerce-blocks/pull/3358) * Correct docblock description * Sync shipping address changes with billing data * Update inline documentation * Revert address sync because it fails when shipping is disabled explicitely * Avoid loading shipping address from customer is shipping is disabled * Rather than update order from the wc/store/checkout request, update the customer object This is turn is synced to order, but also allows the cart calcultions to use the posted data. This means that taxes will be updated based on address data even if not displayed on the checkout. * Add action that combines billing and shipping updates * Add route for updating billing and shipping address * Sync billing data to server on change * Shared constants for billing data * Skip address update if missing country * Allow null values to skip formatting * Add billing to cart schema * Removed unwanted hooks from previous commit * Decoding is handled in useStoreCart * Remove hook * Make shipping context hold state * Make billing context hold state * Add address processors * Cart does not have billing * Update tests, remove some unrelated changes affecting the diff * Revert "Update inline documentation" This reverts commit 0393f49316de3152c6dcf6fda1192c06a74f1b55. * Make shippingRatesAreResolving conditonal based on API request * Shared address processor in cart and checkout * Rename REST endpoint * CustomerDataProvider and hook * Update shipping address type defs * Rename customer address endpoint, and remove update-shipping * Update tests * Fix tests by restoring country validation * typo * Update assets/js/base/hooks/cart/use-store-cart.js Co-authored-by: Darren Ethier <darren@roughsmootheng.in> * Simplify debounce and request handling * Remove state from address sync This will mean billing is "forgotten" if using the checbox, but this greatly simplifies logic. * Rename shipping rates loading to customer data loading * Sync based on useStoreCart data * Made cart API less strict on addresses * Fix useCheckoutAddress sync * Add note on currentShippingAsBilling * Use incoming isCart * Add more detailed inline comment for shippingAsBilling toggle event * Combine customer billing and shipping ref * Update address docblock * Error handling in pluckAddress * Fix cart response after rebase * Update customer tests * Update src/StoreApi/Routes/CartUpdateCustomer.php Co-authored-by: Darren Ethier <darren@roughsmootheng.in> Co-authored-by: Darren Ethier <darren@roughsmootheng.in>
2020-11-20 15:13:35 +00:00
| | [`/wc/store/cart/update-customer`](#update-customer) |
Documentation for the Store API (https://github.com/woocommerce/woocommerce-blocks/pull/2230) * Products endpoint * Updated STORE API docs * Enable nonce protection for checkout endpoints and document * feedback
2020-04-17 09:44:13 +00:00
| | [`/wc/store/cart/select-shipping-rate`](#select-shipping-rate) |
| [`Cart Items`](docs/cart-items.md) | [`/wc/store/cart/items`](docs/cart-items.md#list-cart-items) |
| [`Cart Coupons`](docs/cart-coupons.md) | [`/wc/store/cart/coupons`](docs/cart-coupons.md#list-cart-coupons) |
| [`Checkout`](docs/checkout.md) | [`/wc/store/checkout`](docs/checkout.md) |
| [`Products`](docs/products.md) | [`/wc/store/products`](docs/products.md#list-products) |
| [`Product Collection Data`](docs/product-collection-data.md) | [`/wc/store/products/collection-data`](docs/product-collection-data.md) |
| [`Product Attributes`](docs/product-attributes.md) | [`/wc/store/products/attributes`](docs/product-attributes.md#list-product-attributes) |
| [`Product Attribute Terms`](docs/product-attribute-terms.md) | [`/wc/store/products/attributes/1/terms`](docs/product-attribute-terms.md) |