Case study: Azure API Management

Overview

Azure API Management is a turnkey solution for publishing APIs to external and internal customers. This service helps to create consistent and modern API gateways for existing back-end services hosted anywhere, secure and protect them from abuse and overuse, and get insights into usage and health. Plus, it automates and scales developer on-boarding to help get your API program up and running.
On-boarding of developers happens via the Developer Portal (which Azure API Management provisions for you along with API gateway). Here they can read API documentation, create an account, get subscription key (to be able to invoke the API), and even try making some calls to the API right from the portal using a specialized console.

Content authoring

Administrators of the service, besides managing API documentation (which is automatically generated from API definitions), create lots of additional content like blog posts, newsletters, etc. Here's where Paperbits content authoring tools become very handy: they give users an ability to quickly make up pages, input forms, and email templates without writing a single line of code, and it all looks great on any device. All types of content are created the same way and with the same tools in a consistent, unified fashion.
Besides that, Paperbits ensures content integrity. Thus, changing a permalink of a page, media file, or external resource gets immediately reflected everywhere (including API documentation and email templates). Deleting a referenced resource cannot happen without the user's consent. One can forget about broken links or missing pictures on the page.

Content localization

Often, customers addressing international markets need content localization. Paperbits does not automatically translate the text for you, but it makes it easier to create multi-language content: quickly switch between languages just by pressing a hotkey, go paragraph by paragraph without having to reload the page, leave a comment in the original text for an interpreter to increase translation precision.

Customization

Customization is another area where Paperbits is helpful: the fact is that APIM ships the Developer Portal with a default theme to everyone, and, expectedly, many customers choose to change it to reflect their corporate brand. For this purpose, they use Paperbits theming tools helping them adjust layouts, colors, fonts, spacings, etc. Plus that, more pre-defined themes and design blocks are being added, so customers will have more options and ideas to get started.

Extending

Although Paperbits comes with decent (and continually evolving) theming capabilities, there are always those who want to go further and extend/modify components or add their own. For them, Azure API Management exposes a GitHub repository which anyone can fork and change every single thing on the portal: styles, scripts, templates, etc.
Whenever Microsoft releases a new feature or a fix, customers may merge these changes into the customized fork at their own pace and only if they choose to. Of course, anyone may contribute back to the original repo (through pull requests) and hence, help the community make the product better.
Since Paperbits is, in essence, a static website, the customer-modified version of it can be dropped to any kind of CDN-like hosting (like Azure Blob Storage, which now has support for static websites).

CICD

One of the key concepts Paperbits implements is complete data abstraction: every piece of the content is stored as JSON document, even rich-formatted text. This kind of content plays well with ARM (Azure Resource Manager) template — also a JSON document describing how to provision and configure multiple Azure services (including API management) along with their dependencies.