Kestrel API Manager for WooCommerce

Setting up a WooCommerce store with existing products and orders with the Kestrel API Manager is accomplished as follows:

1. Edit each product to be used with the Kestrel API Manager by selecting the API checkbox, then filling in the API tab form, and if it is a variable product variation, a few API Manager details such as the number of activations.
2. API Resources will be automatically created from Order line items that contain those products selected as API products. Order line items that contain WooCommerce Subscription product types will also be automatically created. All API Resources are now accessible with client software or an online service through the APIs.
3. Either add the Kestrel API Manager PHP Library for Plugins and Themes to your plugin or theme, or build an API client to connect to the API Manager APIs according the the documentation to take advantage of all the features available.
4. Done.

• WooCommerce Software Add-on
  • The Kestrel API Manager has a built-in tool to import WooCommerce Software Add-on data into the API Manager. The API Manager can also answer API queries intended for the WC Software Add-on, so it is safe to delete the WC Software Add-on once the data import has been completed. Clients can migrate at their own pace to new client software that takes advantage of the API Manager’s robust API features.

WooCommerce has an L-1 support policy, which the Kestrel API Manager also supports to keep any dependencies aligned with WooCommerce, WordPress, and WooCommerce Subscriptions when that extension is installed. This means we will support the latest version and the previous version of the Kestrel API Manager. This also means you are required to have installed the latest version or the previous version of WooCommerce, WordPress, and WooCommerce Subscriptions when that extension is installed.

WooCommerce.com has their own chat and support/communication form used to contact them directly. We are a third party developer, so you will need to use this support form for any and all communication with us. If you tried to contact us through WooCommerce.com we will redirect you back to the support form.

Already purchased and need some assistance? Fill out this support form via the Help Desk.

Have a question before you buy? Please fill out this pre-sales form.

1. Fill out this support form via the Help Desk. Without all the details the support form provides about your installation, support is hampered. Support will not be provided if the support form in not used.
2. Provide a clear explanation of the issue, including how support can reproduce the issue, provide screenshots, or provide login credentials for support to see for themselves and take a closer look.
3. Do not talk about how nothing is working, how much it is costing you, or blame the software. Frustration is always an issue when something isn’t working as expected, but it is contagious, and is counterproductive. Stay focused, and follow number 1 and 2. Problems get solved quicker when everyone works together. We are happy to help.

Drop-in library for plugins and themes

A preconfigured Postman .json file collection template is included to make it easy to test the API endpoints. Server URL, and keys/values, will need to be modified specific to your product and server.

The file used for software updates can be hosted on the local server, Amazon S3, or from any remote URL. The file download URL is wrapped in a secure URL that expires after the expire time you set.

The API Manager uses Semantic Versioning, as outlined below:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

A Major version would be 1.0.0 to 2.0.0. A Minor version would be 1.1.0 to 1.2.0. A Patch would be 1.1.0 to 1.1.1. This versioning approach was adopted by WooCommerce in early 2017 as explained in this post.

If you’ve already read the section above on Kestrel API Manager Versioning then you’ll know what a Major version is. When a version goes from something like 1.5.4 to 2.0 that is a Major version, and it means there are breaking changes, so testing is highly recommended, if not required, before applying that update to a live site. WooCommerce has recommendations on how to go about preparing for a Major, or even a Minor, update to make sure your site doesn’t break, or have unexpected behavior. The number one rule to remember is to ALWAYS BACKUP your website before updating to a Major or Minor version.

Always test your current PHP Library in your client software to make sure it works with the new version of the API Manager, especially if a major version is released.

The client software for plugins and themes was called the PHP Library and is now referred to as the Kestrel API Manager PHP Library for Plugins and Themes. As of API Manager version 2.0 the Product ID is required to be sent with each  API call/API request depending on the API endpoint and request type. See the API documentation. As of API Manager version 2.1, there was a change to the API to fix an issue created by some firewalls that block commonly used API call/API request query keys. Variable Products and Variable Subscriptions must send the Product ID (an integer) or software updates will break. Simple Products and Simple Subscriptions can still send the old Software Title, however the Product ID (an integer) is faster, and ensures future compatibility. For these reasons all client software must be updated for  Kestrel API Manager version 2.x. Customers who purchased Variable Products and Variable Subscriptions will need to update software manually, while Simple Products and Simple Subscriptions customers can use the one-click update.

In the main settings, you can enable “Add tabs to frontend product pages” when using a theme that supports tabs such as the Storefront theme. WooCommerce Products will be automatically populated with tabs, and content for those tabs, when the product is an API Manager Product. Just setup the API Products as usual, and the feature does the rest, so you don’t need to write the same content a second time into tab meta boxes on the product.

Settings setup

Amazon S3 Setup Instructions

The API Manager uses SmartCache Engine to cache database and API queries at critical points in the data process to dramatically increase the speed of critical services such as data and API responses. SmartCache only updates the cached data being requested when the data changes, or when expired cache is requested but needs to be refreshed. The result is a dramatic speed increase, and a dramatic decrease in server load. When SmartCache is combined with object caching the result is blazing fast speed. SmartCache allows the API Manager to effortlessly scale to any level of traffic load.

There may be scenarios where API query caching and database caching may not be needed, such as during development and troubleshooting. To disable both API query and database caching add the following to the wp-config.php file:

define( 'WC_AM_ENABLE_CACHE', false );

By default the API Manager signals caching plugins to not cache the homepage/root URL to insure query strings are not cached. This is done to make sure mistakes in caching are not made that would break the APIs. This is also helpful during development and troubleshooting. The API Manager listens for HTTP requests on the homepage/root URL. For store owners that know enough to not break the APIs there are several ways to enable caching on the homepage/root URL.

Add the following to the wp-config.php file to allow the homepage/root URL to be cached:

define( 'WC_AM_DISABLE_HOMEPAGE_CACHE', false );

After caching is allowed on the homepage/root URL exclude the following query string, and anything that follows it, in the caching plugin, or CDN service such as CloudFlare:

wc-api=wc-am-api

See the API docs for more information regarding query strings.

Simple, Variable, and Subscription Product Setup

Setup and Understanding API Manager Subscriptions

After an API product, which is defined as an API Resource, is purchased, an API Key can be used to access that API Resource after the client software activates the access to the API Resource with the API Key. Product Order API Key and Associated API Key are granted limited privileges by the Master API Key.

The Master API Key can be used for any and all API Resources. As API Resources are added or removed, the Master API Key keeps track of those resources, and only allows access to the API Resources available. For example, if a customer buys the same API Resource twice, it accumulates the activations, and if that API Resource is a subscription, then it will reduce the activations when one of the subscriptions is no longer in Active or Pending Cancellation status or add more activations when a new subscription for that API Resource is added.

The Product Order API Key and Associated API Key get their privileges from the Master API Key, and only manage a single API Resource from a single order. If a new order for the API Resource is generated, a new Product Order API Key is generated to manage that API Resource, which means the customer will need to deactivate their software and reactivate using the new Product Order API Key. This is especially true if the API Resource is a subscription. It is always best practice for subscription customers to use the Master API Key.

There are several types of API Key, or Licensing, models that exist, for example node-locked, OEM, and floating.

• A node-locked license is an API key for use on one computer, and is tied only to that computer.
• An OEM license unlocks software preinstalled, for example, windows using an API Key.
• A floating license is an API Key that can be used to unlock a computer or software if there is a free license available.

The API Manager uses a floating and OEM license model for API Keys. The API Manager assigns a limited number of API Key activations per product purchase. When an activation is used, there is one less activation available for other software or computers to use as in a floating license model, and if an activation is deactivated, then that activation can be used by other software or computers. This model can also be used for OEM.

The Product Order API Key can limit those activations for a specific product on a specific order.

The Associated API Key can use imported, or local server generated API Keys, assigned to a product, and then assigned when an order is placed for that product. The Associated API Key could be as an example, Windows OEM license keys customers can use to activate their product.

The API Manager expects the API Key used to request activation, along with other values as defined by the API endpoint, documented below.

The store administrator can control the user Master API Key under Users > “user profile.” Under the API Manager API Key section, the Master API Key can be replaced, and disabled, but never deleted permanently. If the Master API Key is disabled, the Product Order API Keys, and Associated API Keys, available to the user will also stop working. A disabled Master API Key means no access to API Resources for the customer.

If the Master API Key is replaced, all activations for the user who owns the Master API Key will be deleted. Activations created using the Product Order API Key, and Associated API Key, are also deleted when the Master API Key is replaced. Product Order API Key and Associated API Key are granted limited privileges by the Master API Key.

When the API Manager API Key > Disable Master API Key box is checked on the User Profile, the user will no longer have access to any API endpoints even if valid activations exist. The user account will be completely disabled, and the My Account dashboard will reflect this disabled status.

The User Switching plugin is a very useful tool that allows the store owner/manager to virtually login as a user. Once switched to the user login the user’s My Account dashboard can be viewed, along with the API Keys and API Downloads tab. This is useful when troubleshooting, investigating issues, and confirming template overrides are working as expected from the user’s view. Don’t forget to switch back using the switch link. Do a Google search for tutorials on how to get the most out of the User Switching plugin.

By default API Resources only exist for orders that have a “completed” status. API Resources for the order status “processing” will only exist if WooCommerce > Settings > Products > Access Restriction > “Grant access to downloadable products after payment” is selected. Orders that have a “processing” status before “Grant access to downloadable products after payment” is selected will not have API Resources available until the order status has changed to “completed,” or the order is new and has a “processing” status, or has been changed to “processing” status.

Orders not in completed status, or processing status if other conditions are met, will have the API Key activations, and API Resources, deleted. If the order is placed back into completed status, or processing status if other conditions are met, the API Resources will be recreated, but the API Key activations will not. Why are activations deleted? Client software will, or should, receive an error if it tries to send a query with a Product ID that is no longer considered active, but the customer may not realize he/she would need to delete activations in his/her My Account dashboard before reactivating the client software, so those activations are deleted to eliminate known support issues customers commonly have related to this. All the customer should have to do once they have brought their account back into good standing is to reactivate their software.

See the WooCommerce Subscriptions section regarding Subscription statuses.

Order Screen Features

How the API Manager Works with WooCommerce Subscriptions

The API Customers dashboard.

The API Customers dashboard lists essential details for each customer. Each API Resource represents an order line item that is an API Product. Some columns are sortable. The search box can be used to find API Resources by email address, Order ID, Product ID, or by a User ID. The email address has been obfuscated in the screenshot above.

There are links to additional resources that open in a new tab. For example, to manage the number of activations or extend its expiration time, the Order ID link will open the order for the API Resource, and the API Key activations can also be viewed or managed on the same order screen.

Features of the My Account Dashboard

API Specifications and Documentation

Templates in the Kestrel API Manager can be overridden using the same approach as is used to override a WooCommerce template. Directions are as follows: https://woocommerce.com/document/template-structure/.

The API Manager can be used to prevent software, or a service, from being used until after the API Key has been activated. The documentation for the Kestrel API Manager PHP Library for Plugins and Themes has an example on how to prevent use of software until after the API Key has been activated. This method can also be used to disable software if the API Key has expired. How this is implemented is completely up to the software author. A close examination of the API endpoints will provide more information on which will be needed to take appropriate action.

The approach taken most often is to allow the customer to continue using the software after the API Key has expired, just like a desktop version of the software would, but to deny software updates, which the API Manager will do if the API Key time limit for that API Resource has expired. If the software is still in use the customer can still see if software updates are available even after the API Key time limit has expired, but the customer cannot get the update until they renew the API Key time limit through a new purchase, or renewing a WooCommerce Subscription.

Troubleshooting options

Load and speed benchmark test results