search

woocommerce / woocommerce-legacy-rest-api

The legacy WooCommerce REST API, which used to be part of WooCommerce itself but is removed as of WooCommerce 9.0.
11 stars 11 forks source link

Add initial plugin code and README file #1

Closed Konamiman closed 1 year ago

Konamiman commented 1 year ago

Context: The Legacy REST API will move to a dedicated extension in WooCommerce 9.0

This pull request adds an initial version of the Legacy REST API extension code and the README file to an otherwise still empty repository. It's intended to be tested together with WooCommerce, both with the latest one (still having the Legacy REST API built-in) and with a build that has the Legacy REST API removed (https://github.com/woocommerce/woocommerce/pull/40627).

Installing the extension

In a local environment: clone the repository directly inside the wp-content/plugins directory of the same WordPress install where you have WooCommerce (so the directory where all the plugin files are located is wp-content/plugins/woocommerce-legacy-rest-api).

In a remote test site: clone the repository, put all the files inside a woocommerce-legacy-rest-api directory (it can be the same wp-content/plugins/woocommerce-legacy-rest-api directory if you have tested locally already) , and create a zip file containing that directory. Then you are ready to install the extension using the WordPress plugin install UI (Add New - Upload Plugin).

Testing the extension

Testing the extension boils down to testing that the Legacy REST API continues working as expected, so the API documentation itself is the way to go. But in a nusthell:

  1. Go to WooCommerce - Settings - REST API and press "Add key" to generate a new pair of consumer key and secret (you can skip this step if you already have a working pair).
  2. Try any of the API endpoints, for example: http://localhost:8034/wc-api/v3/orders. If you are testing locally (so no HTTPS) you'll need to use a tool capable of handling the OAuth authentication (e.g. Postman); otherwise: curl http://thehost/wc-api/w3/orders -u <consumer key>:<consumer secret>
  3. When the Legacy REST API isn't enabled (setting disabled in WooCommerce <9.0, extension not installed in WooCommerce >=9.0) the response from the API is always like this:
{
    "errors": {
        "code": "woocommerce_api_disabled",
        "message": "The WooCommerce API is disabled on this site"
    }
}

Additionally, webhooks that are configured to be delivered with the legacy REST API payload format will continue to work when the extension is installed, and will fail "gracefully" (an exception will cause the delivery scheduled action to fail with an informative message) otherwise. More on that later.

Testing with old WooCommerce

Here "old WooCommerce" means any WooCommerce (it can be the latest released version, or the current trunk) that doesn't have https://github.com/woocommerce/woocommerce/pull/40627 applied.

  1. Deactivate the extension if you had already installed and activated it (via WordPress plugins UI or wp plugin deactivate woocommerce-legacy-rest-api/woocommerce-legacy-rest-api.php).
  2. Disable the Legacy REST API (WooCommerce - Settings - Legacy API, or wp option update woocommerce_api_enabled no
  3. Install (if it isn't installed yet) and activate the extension (activate via WordPress plugins UI or wp plugin activate woocommerce-legacy-rest-api/woocommerce-legacy-rest-api.php).
  4. Verify that the Legacy REST API is still disabled (via realoading the settings UI page or wp option get woocommerce_api_enabled, expected value is no).
  5. Enable the Legacy REST API (via settings UI, or wp option update woocommerce_api_enabled yes)
  6. Deactivate the extension again.
  7. Verify that the Legacy REST API is still enabled (via realoading the settings UI page or wp option get woocommerce_api_enabled, expected value is yes).
  8. Test the Legacy REST API itself with and without the plugin active.

Testing webhooks

  1. Make sure that the extension is active.
  2. Create a webhook for any action that is easy to trigger (for example, "coupon updated") in WooCommerce - Settings - Advanced - Webhooks. Select "Legacy API v3" as the API version to use. You can head to https://webhook.site/ to get a test URL to use as the delivery URL.
  3. Try the webhook by triggering the appropriate action (e.g. updating an existing coupon for a "coupon updated" webhook) and verifying that the delivery URL is hit. Note that the delivery is done via scheduled action, so you may need to trigger it manually (in WooCommerce - Status - Scheduled Actions; the action name is woocommerce_deliver_webhook_async).

Testing with new WooCommerce

Here "new WooCommerce" means WooCommerce with https://github.com/woocommerce/woocommerce/pull/40627 applied. You can check out the pull request branch locally, or use the WooCommerce Live Branches feature offered in the pull request itself.

Once the new WooCommerce is installed, and without the extension active, going to WooCommerce - Settings - Legacy API should look like this:

image

Trying to query any of the Legacy REST API endpoints should result in the "WooCommerce API is disabled on this site" error being returned.

After installing and activating the extension the settings page should have changed to:

image

...and the Legacy REST API endpoints should work as usual.

Test also the /wp-json/wc/v3/settings/general/woocommerce_specific_allowed_countries endpoint as it was using code that belonged to the legacy REST API package and has been moved to WooCommerce core.

NOTE: The value of the disabled checkbox is taken from the woocommerce_api_enabled option, which for compatibility will continue to be yes when the extension is enabled and no when it's not (controlled by the activation/deactivation hooks of the extension). In fact, if the option has a value of no the Legacy REST API endpoints will continue to return the "WooCommerce API is disabled on this site" error even when the extension is active.

For now, if an old WooCommerce that has the Legacy REST API enabled gets upgraded to a new one, the option will still be set to yes even if the extension is not installed. To fix this an upgrade migration needs to be added to https://github.com/woocommerce/woocommerce/pull/40627 so that if the Legacy API is enabled and the extension is not installed, the option value is changed to no (also this would mean that the site is broken so we should probably add a loud admin notice too if that happens, or try to auto-install the extension).

Testing webhooks

  1. With the extension active, repeat the "testing webhooks" part of "Testing with old WooCommerce". Nothing should have changed.
  2. Deactivate the extension.
  3. Reload the webhooks settings page. Now you'll see a warning message and a warning icon next to the webhooks that are configured for delivery with the legacy REST API:

image

  1. Open the details of one of the webhooks. Note that in the dropdown to select the API version, the "(deprecated)" note next to "Legacy API V3" has been replaced with "(NOT AVAILABLE)":

image

  1. Try performing the action that delivers the webhook. The delivery won't happen, and the corresponding scheduled action will be listed in the "Failed" section with an informative error message:

image

Konamiman commented 1 year ago

@barryhughes readme.txt added, please check if something is incorrect or missing (especially in the list of contributors and tags).

barryhughes commented 1 year ago

Great, thanks @Konamiman! Left a couple of suggested tweaks but A) they are minor, so pre-emptively hitting approve so you can merge as soon as you and Jorge are happy B) confirmed the readme.txt file is valid :+1: