In 2.5 we introduced the ability of pushing custom policy schemas to the UI so those policies can be used in policy chains. These changes are made via APIs (not UI) or automatically when deploying APIcast, and they need to be fully documented. The thinks to consider when writing documentation for SaaS or on-prem are slightly different:

On-premises

• Custom policies need to be included in APIcast, a new image needs to be build (both of those things are already documented) then those policies will automatically show as available in the UI when the gateway is deployed with that image (this is the part which I believe is not mentioned anywhere).
• Since 2.5, you could also push the policy schemas to the UI using APIcast command line (this is less relevant in onprem because potentially you won't need it).
• Document what happens if custom policies are removed/added: when a custom policy is added and the gateway gets restarted, existing services will see this new policy in the list of policies available so it can be used in any policy chain. When a custom policy is removed from an image and the gateway is restarted a) the policy will no longer be available in the policies section, so it won't be possible to add it to a policy chain anymore 2) policy chains that were using that policy will still show it, however, APIcast will just ignore it. An error will be shown in the APIcast logs.

SaaS (APIcast self-managed only)

• It's important to differentiate between custom policies, and policies which are standard but are not available for APIcast hosted.
• APIcast hosted does not support custom policies.
• For standard policies which are not available for APIcast hosted, we want to make them visible by default in the UI when APIcast self-managed is selected. See JIRA issue https://issues.jboss.org/browse/THREESCALE-1966
• For custom policies, the way to make them available in the UI so they can be used in a policy chain, (after creating the policies and rebuilding the image, just like in SaaS) would be using APIcast command line to push the policy schemas (available since 2.5). Use --help command to learn about this option (no upstream docs). See example command output in THREESCALE-871
• Document what happens if custom policies are removed/added (same as for on-premises)

tmaas-1 dortiz-1 I am leaving out on purpose using the system API directly (although could be valid for APIcast versions < 2.5) so we're consistent between SaaS and onprem.