A Guide to API Types and Integration Specifics

There is plenty of information on the different types of APIs, common API architectures and protocols, and such. So, instead of providing general information, I decided to take a look at all these concepts specifically from the integration perspective including:

• What exactly working with different types, architectures, and protocols of APIs means when you want to integrate several services with each other
• What tools can be useful in such cases and what aspects you might need to be aware of. 

So, let’s kick off this topic with the first part – the different types of APIs and their integration.

Types of APIs and the Integration Intricacies

Commonly, there are four types of APIs that are seen as prevalent: public, private, partner, and composite. In this sense, the word “type” is applied here to the intended scope of API’s use.

Public APIs

Public APIs are also sometimes referred to as open or external APIs and as the name suggests, are openly available to anyone with either no or relatively minimal restrictions. They are essentially a way for a third party to communicate with a web application that a company has developed, and most large and small businesses provide public APIs – PandaDoc, BigCommerce, DocuSign, NetSuite, and many more.

How to Integrate With Public APIs

Integrating with public APIs is relatively easy: The respective companies will provide you with the necessary API documentation that will describe the endpoints, the ways to authenticate/authorize their API for your use, the methods to call these APIs, and so on. In fact, any enterprise integration platform is basically built around the “concept” of public APIs, providing the so-called integration connectors that are essentially abstraction layers to respective web applications’ APIs.

The complexity and the scope of work will then depend on how well the API was designed and documented.

There are, by and large, two main strategies to integrate with public APIs: Either you use third-party software such as iPaaS, or you do it yourself. When you opt for the latter, though, be prepared to design a good strategy for data mapping. While many applications use the same pattern for naming common fields on the frontend, these fields can have very different labels “behind the scenes”. A proper strategy is your guarantee for traceability, accuracy, and relatively fast project implementation as well as protection from some easily avoidable errors.

A side note: If you’re looking for some openly accessible APIs for your own pet project, there is a non-exhaustive list of public APIs on GitHub, ranging from completely open such as weather web apps to requiring an API key or OAuth authorization.

Private APIs

Being the opposite of public APIs, private APIs are solely meant for use within a single company. Often they are used by corporate developers to enable some level of data exchange between web applications, give access to corporate databases and other internally shared services, communicate with other internal APIs, or build internal apps for the company’s employees.

In fact, more and more companies recognize the value of consuming their own APIs, since this approach is generally time- and resource-saving, promotes agility and flexibility, and helps reduce operational costs.

How to Integrate With Private APIs

Since private APIs typically reside in highly secure environments, integrating with them – should you need that – requires sending calls through very restrictive firewalls or a VPN service (that is, if external access is allowed in the first place). This means that if you’re wondering whether your company’s integration middleware can be of any help, you should check if it has some sort of mechanism/security layer to access local systems and web applications.

It’s also worth pointing out that some aspects that are essential for the success of public APIs are often seen as less necessary in the case of private ones; the security mechanisms are either lax or missing – since they are assumed to be already protected by the companies existing security policies – developers often use internal or technical names in the documentation, the versioning is not necessarily included in the design.

This might make integrating with a private API challenging for new team members or other departments, no matter what approach your company advocates for – manual coding or an integration middleware. So, if you happen to be someone who’s in charge of designing private APIs in your company, approach them as if you were designing public APIs, with all API best practices and checks in place.

Partner APIs

Partner APIs fall into the category of internal APIs but rather than being used within one organization, these APIs are typically shared between business partners and B2B clients. A common use case would be connecting two internal business software applications in supply chain integration or point-of-sale integration. In such a scenario, APIs act often as an alternative to the classic EDI integration.

Partner APIs are usually characterized by more robust authorization, authentication, and security features, since they often give outside parties access to sensitive data – such as customer data with a partner’s CRM or ERP application, or patients’ medical data with medical institutions and practitioners.

How to Integrate With Partner APIs

Since partner APIs are not openly available, you shouldn’t expect to find an integration solution that will allow you to “hook these up” on the fly. If your company offers partner APIs or you’re the one who is supposed to integrate with such an API, you’ll either need to revert to the good-ol’ manual coding or look for an integration middleware that enables self-service custom connector development.

Sometimes you might be required to connect a partner API with an EDI-based web application, in which case you’ll need to transform various data formats, e.g. EDIFACT to JSON. A good enterprise integration platform should be able to support that. Alternatively, you could use a dedicated parser such as this Javascript stream parser for UN/EDIFACT documents.

Composite APIs

For me personally, composite APIs are the most fascinating type. Consider a typical process such as order creation in a shopping cart. This will require making several API calls to multiple endpoints: to create a new customer, create a new order, add an item to this order, to list just a few. A composite API can do all that in one single call, which certainly speeds up the task processing and performance. For example, consider the composite REST API from Salesforce: 

{
"compositeRequest" : [{
  "method" : "POST",
  "url" : "/services/data/v52.0/sobjects/Account",
  "referenceId" : "refAccount",
  "body" : { "Name" : "Sample Account" }
  },{
  "method" : "POST",
  "url" : "/services/data/v52.0/sobjects/Contact",
  "referenceId" : "refContact",
  "body" : { 
    "LastName" : "Sample Contact",
    "AccountId" : "@{refAccount.id}"
    }
  }]
}

Their documentation mentions that you can have up to 25 so-called subrequests in a single call with this API.

Another scenario where composite APIs can prove themselves useful is pulling information from multiple services to complete a single task in a microservices architecture pattern. By the way, composite APIs don’t necessarily require the creation of a completely new API. In many cases, you can just augment the design of an existing API by wrapping several calls or requests in one sequence.

How to Integrate With Composite APIs

When it comes to integration, a composite API doesn’t differ much from a regular public API. In fact, if your integration platform solution has a generic connector for REST or SOAP, you can easily use it to connect to a composite API. 

Integrating With Different API Architectures and Protocols

Let’s now briefly go through the options you have when working with APIs that have different architecture and/or protocols, which will define the accepted data types and commands. Most of the time, you’ll probably be dealing with REST and SOAP APIs.

As you probably already know, the two are often treated in tandem, when in fact, REST is an architectural style whereas SOAP is a protocol. They do share some similarities which sometimes make integrating them with one another relatively easy – for one, both can communicate via HTTP and XML. But the differences are far more profound.

For example, to expose specific portions of a web application’s business logic on a server, SOAP employs a service interface whereas REST uses URIs. REST APIs support a variety of data formats, including plain text, XML, JSON, and CSV, whereas SOAP only supports XML. REST is also generally considered to be more lightweight and consumes fewer resources than SOAP.

Now, what about your integration options? Considering the differences, we will require some kind of a translation between the two APIs. When you work on integrating these APIs manually, you can automate this with a tool like Postman. For example, you can call one web application’s SOAP API and have the XML returned parsed for the data that you require. After that, you can convert this XML to e.g. JSON, and push these data to another web application’s REST API.

When your company has implemented an integration software, it will make your work a lot easier, since such a platform can be expected to take care of this kind of data transformation between REST and SOAP-based web applications and services by default.