Microservices are very much in vogue as an alternative to monolithic applications. It’s no wonder because microservices-based architectures simplify scalability, reduce application development time, enable innovation, and shorten the time-to-market for new features. As a rule, microservices are deployed in a cloud and use their own or external APIs. The increasing prevalence of cloud plays a crucial role and makes Web APIs more important.

What's more, numerous standards, such as the travel and automotive industries and the healthcare sector, and regulatory requirements such as the PSD2 payment services directive, also fuel the issue. For example, PSD2 regulates which interfaces can be used for online payments.

However, the development and use of APIs in document management are not only relevant to an IT department. Because it affects an entire business, all players in a company should be involved. After all, there is a high monetization factor – there is good money to be made with self-developed services.

That applies not only global players but also small and medium-sized companies with the opportunity to expand their existing fields of business. Finally, our economy and society’s general digitization is a strong growth driver of API document management. Electronic communication between companies, public authorities, and citizens or consumers is becoming widespread – and this requires appropriate interfaces.

The following two scenarios demonstrate how the intelligent use of microservices based on APIs can improve the automation of various processes and help both the user and the company add value.

Case Study 1: API Document Management for the Settlement of Hail Damage

Following a storm, an insurance company’s claims department receives numerous customer recourse claims. To rule out possible insurance fraud and determine whether each claim is justified, the claims processor needs detailed information about the storm’s time and location. When and where did the hail occur, and how intense was it? Was the insured's residence within the storm's catchment area at the time of the claim? Can the described damage to the building or vehicle really have been caused by the storm, or is it possibly older damage?

The claims adjuster usually uses an external weather service, whose app easily connects to the insurer's IT infrastructure via an API. Right in his or her specialist application, the employee can request detailed weather reports for a specific region, county, or location on any day. It’s also possible to focus in on the street and time. That information forms the basis for deciding whether to accept or reject the recourse claim. By integrating an external special application into existing processes, it’s possible to process claims much more quickly.

Case Study 2: Generating Barcodes via API

Compart, an international manufacturer of software for omnichannel customer communication, offers a barcode-generating tool on its website. Using a Compart-provided API, one can generate a barcode and transfer it to their own system for further processing, such as document and output management. The user registers on Compart's homepage, receives an access code, and then accesses the barcode generator's Web API directly in the specialist application. Instead of investing in their own barcode generation software, the prospective customer uses Compart's API service directly.

There is generally high motivation to use Web APIs for document management. Not only do they save valuable resources, as they do not require in-house software development, but existing products or services can also be expanded quickly and easily. Web APIs also enable interoperability between external and internal systems, opening up opportunities for new business models and partnerships with other companies.

For example, consider a health insurance company and medical institute for infectious diseases working together. The medical institute’s information could help the insurer recognize and evaluate dangerous situations quickly. Together with health providers, it could develop early and effective therapies for insureds. That could also be implemented via a corresponding Web API service.

REST Is Not the Only Option

Eighty percent of all Web APIs in use today are based on the REST architecture. Strictly speaking, that is not a protocol but an approach to using HTTP to describe certain constraints and the interaction between virtual machines, systems, and applications. What is interesting is that HTTP was not designed for APIs, but Web pages. So why is REST so widely used?

On one hand, its architecture is simple to understand. It can also be implemented much faster than others, such as the complex SOAP protocol, which was especially prevalent from 2000 to 2010 and is still used today. SOAP was developed for interaction between servers, not for client-server communication. In addition, SOAP is very powerful and requires deep programming knowledge.

In contrast, REST is kept relatively lean, and it’s generally easy for someone who understands HTTP to some extent to grasp or implement. Nevertheless, the REST architecture has limitations. Since it’s not a globally valid standard, it allows for free interpretation in application and development. Interpretation is free, as in “everyone can do what they think is right.” The number of different implementations is correspondingly high.

This is where the problem lies. While the application of REST API may be simple, its clean implementation – good design, detailed and understandable documentation, and stringent management—represents a significant organizational challenge. Also, CRUD operations for databases and static data stores tend to be limited with REST.

And the REST architecture is not ideal for implementing requirements such as IoT, AI, and bots that require other types of APIs. Another challenge with REST is that you always have to request the entire resource – even if you only need a single, small property or attribute. This ‘overfetching’ can be a serious drawback of REST APIs.

There are serious alternatives, such as gRPC, RSocket, W3C SPARQL, GraphQL, JSON:API, and OASIS Odata. Google’s gRPC protocol reflects the modern world of API communication in a way. The protocol, also used outside of Google, is a more lightweight approach than the powerful SOAP, and it’s very efficient at processing data.

One usually comes across gRPC being used in communication between a company’s systems. That mainly involves communication via a binary transport. In short: When developing an API strategy, one should not rely exclusively on REST but should also examine alternatives.

In the meantime, many companies and organizations have published guidelines for handling and using APIs. These guidelines describe, for example, how to secure APIs, which naming conventions apply, which HTTP headers are supported, what error messages should look like, and more. They are intended for both programmers within a company and external users to develop and use API services in compliance with the rules.

For example, anyone wanting to integrate Zalando's search platform into their company’s portal needs to know the online retailer's API guideline in detail and take it into account for implementation. Since many companies make their rulebooks publicly available, it’s an important source for companies that have just started dealing with API.

One could say they benefit from that cross-company knowledge transfer because they can learn from the “old hands’” experiences and be inspired by successfully implemented API projects. Find a current overview at http://apistylebook.com/design/guidelines/.

API for Document Management - Best of Breed, or All on One Card?

One thing is for sure: APIs as business-critical factors require strict management and governance. The technological ecosystem has never been as rich as it is today. It’s easy to lose track of things. Therefore, a straightforward API strategy is extremely important. It’s important to remember that REST doesn’t solve all problems. There are other good architectures and approaches, too.

Ultimately, a specific business question (i.e., What do you want to achieve by establishing an API economy?) and an extensive analysis of the existing structure is decisive. A company should not rely solely on one provider of external API services, and it should keep an external service provider’s influence on its own infrastructure as low as possible.

Companies that focus exclusively on one API service provider risk not being able to access services one day if there are sudden market changes – for example, if providers and customers suddenly become competitors due to the similarity of their business areas or if there are legal disputes.

The case of PeopleLinx, now Frontline Selling, is worth remembering. The company, founded by former LinkedIn employees, was suddenly denied access to its API services one night by LinkedIn. The accusation was that PeopleLinx tapped LinkedIn data without permission and made it available to other companies. According to LinkedIn, this violated contractual provisions regarding the use of APIs. Suddenly, PeopleLinx was left without much-needed API services.

Data protection violations are not infrequently the reason cooperation’s within an API economy fall apart. Many remember the Cambridge Analytica scandal. The analytics company, founded by the British SCL Group, had tapped Facebook data without permission and used it for targeted marketing messages promoting Brexit in the UK. That was possible because of vulnerabilities in the APIs provided by Facebook.

DocBridge® Impress: Document Creation as an API Service

The examples above make several points clear. On the one hand, one should not become too dependent on external API services and certainly shouldn’t "back only one horse." It’s better to use different providers’ services and develop an emergency plan early on. What would you do if, for whatever reason, you no longer have access to an API service? What are the alternatives?

On the other hand, it’s critical to contractually regulate exactly who may use the API service for what purpose and to what extent to avoid any nasty surprises, such as happened with Cambridge Analytica.

It’s difficult to answer the question of whether to rely on large established API providers, such as Amazon, Google, or Microsoft, or on "best of breed" specialists, even if they have an outstanding product as niche players. The answer varies, depending on the business case and its needs.

Today, various platforms offer a wide range of API services from different service providers, such as Rapid API (www.rapidapi.com). Among other things, a number of services for text analysis can be found there, which could be useful for companies' marketing. What do customers think about certain products? What do social media users think about the company? Do they recommend it to friends, acquaintances, or family members?

Especially in customer communications such tools for API based document management play an increasingly important role , for example, when incoming messages, whether digital or on traditional paper, need to be analyzed to determine their tone. Does the customer threaten to call a lawyer, set deadlines, or put forth a linguistic threat?

The analysis and resulting conclusions are important for prioritizing individual communication processes and a correspondingly rapid processing of the case. Such API services can also be to classify and track documents in general.

Additionally, language scoring can be used to analyze a text’s degree of difficulty. How comprehensible will the content be for the respective target group? Of course, that depends on the professional and private background – native speaker, level of education, and general understanding.

For example, suppose a white paper is too scientific (i.e., the scoring value is very high). In that case, sentences and text passages can be rephrased, sentence structure simplified, or fewer foreign words used. In other words, one can make the content appropriate for a target group.

But the delivery form of a piece of content also plays a decisive role in customer communication. Today, documents must be created so they can be sent or displayed, according to the wishes of the recipient, on every analogue and digital medium. To achieve this, document creation must break away from the so-called Letter-page paradigm.

With DocBridge Impress, for example, Compart offers a powerful solution for page- and device-independent document design – not only as client software but also as a container within Kubernetes in a cloud. DocBridge Impress can be connected to the customer's infrastructure via an API.

With the composition solution, documents can be created and sent to all relevant channels, and displayed on different media – including printed pages, a PDF in an email attachment, a responsive HTML page in a web browser, on a smartphone or tablet, and via messenger services, for example.

Each new document must only be generated once, and then is available for all types of media without needing conversion. DocBridge® Impress represents a paradigm shift in document design: creation is independent of a given page size, and is based on open standards.

Further features are:

- HTML5-enhanced with print-relevant functions

- Deposit of business and language logic

- Integrated management of templates, images, text modules, and other resources for consistent and coherent documents

- Individual preview for each output channel during creation ("What You See is What You Mean")

- API Document Management - What Matters?

- Design/build, execution/development, implementation, management, and security

- Its API-driven approach lets you invest more time in design

- Select the best approach early (best-of-breed)

- Documentation, usability, and testing are critical

- Versioning strategy – APIs are evolving, so determine how to version them and how often to make updates

- Pay attention to the latest versions of external API services early on, so you can upgrade them in a timely and secure manner

- Precisely define the procedure for transitioning from test to the productive environment. Deployment, staging, integration, and registration – what should the integration look like? Which registration mechanism should be established?

- Use API gateways as single entry points. Advantages: Decoupling clients from internal services, increased security, simplification of internal services, and more robust central monitoring, which is important for billing and identifying potential bottlenecks. Most cloud providers (including AWS, Azure, and Google Cloud) offer such API gateways.

https://www.compart.com/en/home

Carsten Lüdtge is in charge of the Compart Group’s entire content management. Originally published at https://www.pdfa.org/driving-efficiency-in-customer-communications-through-api/