Document introducing custom endpoints on the StoreAPI

[xristos3490]

Description

This request originated from an internal discussion (pdqkbG-1iZ-p2) about whether handling/adding extension data on the cart resource is applicable. If not, developers must be able to extend the StoreAPI using custom endpoints that will serve their data to the React application.

For visibility, here's the quote that kick-started this entire discussion:

If any of the following statements are true, choose to extend the Store API rather than contributing new data to the Store API:

- The data is part of an extension, not core.
- The data is related to a resource, but not technically part of it.
- The data is difficult to query (performance wise) or has a very narrow or niche use-case.

If the data is sensitive (for example, a core setting that should be private), or not related to the current user (for example, looking up an order by order ID), choose to use the authenticated [WC REST API](https://href.li/?https://woocommerce.github.io/woocommerce-rest-api-docs/#introduction)

That said, here are some of my questions when I first started analyzing the work for a new custom endpoint: (there are a lot 😅)

The PHP side:

• Is this safe to assume that we can extend the AbstractRoute and/or the AbstractCartRoute classes?
• The RoutesController and the SchemaController don't include any hooks to add custom endpoints. Does this mean we must implement the endpoint from scratch using the register_rest_route() function?
• If the above is true, how do we handle an un-authenticated endpoint from scratch? Is there a recommended way to introduce a custom endpoint using reusable PHP classes? What about nonces?

The JS side:

• Do we need to implement manual nonce handling for POST requests?
• Do we need to introduce redux stores for our data/endpoints? Is this example getting out of the scope of this doc request? Meaning that redux stores are "up to us" and depend on how complex is our case? Is a simple request/fetch (in a useEffect() context) in a component enough to showcase the usage? (probably yes)
• Is there a way to work with authenticated WC endpoints without exposing Rest API keys? How the WC Admin handles the requests using the WC Rest API? Should we implement something similar somehow?

Please keep in mind that I'm unfamiliar with architecting React applications, and these questions might come in as "noob-ie." Still, given that the average WP developer isn't familiar with the process, I believe we need to showcase a simple example from start to finish.

Perhaps we could document on two different resources:

• An example with an authenticated rest endpoint, and;
• An example with an un-authenticated rest endpoint; and a nonce handling case when dealing with POST requests.

[wavvves]

Is this safe to assume that we can extend the AbstractRoute and/or the AbstractCartRoute classes?

I would say yes. We would want to enforce this type of consistency for custom routes if we want to take care of any heavy lifting for third-party implementing custom routes (ie registering routes).

The RoutesController and the SchemaController don't include any hooks to add custom endpoints. Does this mean we must implement the endpoint from scratch using the register_rest_route() function?

Definitely, there is a chance to improve the Store API init. I would say yes to that question. In theory, third-party could extend the RoutesController, define their own $routes property, and add an action to 'rest_api_init' calling the register_all_routes() method for that class. In realistic terms, it doesn't seem to be worth it since we're hardcoding versioning and namespacing and without re-declaring the whole class we would be limiting the freedom for that.

IMHO, this would represent a good point to justify refactoring StoreApi, RoutesController, etc, and include proper support for custom endpoints to be added. Also, judging by the unused imports on those files, they look like good candidates for reviewing 🤔

EDIT: I misread the namespace, those are not unused imports, just unnecessary ones.

[mikejolley]

The above quote:

If any of the following statements are true, choose to extend the Store API

Is referring to the schema extend classes for existing Store API routes, specifically these:

https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md

If an extension has unique needs that require a new route, there is nothing to extend. register_rest_route would be used (on the rest_api_init hook), and for that, all WordPress Rest API documentation applies:

https://developer.wordpress.org/reference/functions/register_rest_route/

There would be no requirement to extend Store API classes such as AbstractRoute, in fact that would probably make the task more difficult because of how Schema classes are hooked up.

As for authentication, this is something defined by the route:

https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/#permissions-callback

For StoreAPI, permission callback is just set to __return_true (no permission needed). Store API does not cover authentication nor have a recommended way of providing authentication to extensions.