How to Evaluate the Public API of a Software System

By Riyad Mammadov, Vice President, Application Development

When insurance companies choose a software system, an important consideration should be the level of sophistication of its public API. Gone are the days when applications could afford not to have APIs at all. The era of monolithic Enterprise Resource Planning systems is behind us. Contemporary software systems are focusing on a few specific features, and because of this, they must have the ability to integrate with each other. Even though vendors could try and create built-in interfaces for various party systems, it is impossible to cover all possible integration scenarios. File-based integration is too rigid and doesn’t play well in the world of mobile apps and interactive websites.

So, what should we look at when we are evaluating the public API of a software system?

Protocol. Older APIs were built around the SOAP (Simple Object Access) protocol which became popular around the year 2000. SOAP relies on XML to serialize data and build special envelopes around the payload, creating considerable overhead because of XML verbosity and parsing speed. Contemporary APIs utilize REST protocol (Representational State Transfer), which is a set of guidelines for creating stateless web-based APIs built around standard HTTP methods such as OPTIONS, GET, POST, PUT, PATCH, and DELETE. The de facto standard payload format for RESTful APIs is JSON (JavaScript Object Notation) which has approximately 20% less overhead than XML.

Authentication. The industry standard for reliable and secure authentication is OAuth2. Under this protocol, a client submits an authorization grant (for example, client credentials) to the server and receives an access token in return. The token – when converted to text form – is just a combination of letters and numbers; it represents specific scope and duration of access. All subsequent client requests to the API must include this access token until it expires.

Whitelisting. Whitelisting is a cybersecurity strategy that provides web service access only to clients that an administrator has explicitly allowed. The most common approach is to whitelist specific IP addresses or address ranges. This is an extreme measure, but it can reliably prevent unauthorized access.

Coverage. The functionality of the API should mirror the functionality of the software system. Although a 100% match between the two is usually not feasible, it must be close enough so that all major workflows can be accomplished using either manual interaction with the system or programmatic interaction with the API.

Method-Level Security. A good public API will support multiple integrations that have different credentials and allow a different set of methods (functions). With this approach, users can create focused integrations (e.g., one for an accounting system and another for a rating system) and further reduce the possibility of a cyberattack.

Impersonation. Sometimes it is important that transactions processed through the API can be attributed to a specific organization employee. In order to support that, API should allow the client system to authenticate on behalf of a user. This mechanism must be secure enough to prevent users from hiding their transactions under someone else’s name.

Callbacks. Traditional API calls represent a “pull” mechanism: the client makes a call to the service to retrieve data or process updates. Callbacks (also known as webhooks) are the “push” mechanism: they allow the client to register a special callback URL with the service, then have the service invoke the URL in response to certain events. Callbacks allow real-time two-way communication between the client and service. For example, under the “pull” model, the client must continuously poll the service to check whether unpaid invoices are available. Under the “push” model, the service will automatically invoke the callback as soon as the invoice is posted.

Considering the items above will give you peace of mind that the system you are evaluating can effectively and securely participate in enterprise integration workflows.

Related News