Types of APIs

Introduction

Most merchants do not want to be constrained by third-party software providers but lack the resources to develop proprietary business solutions from scratch.

APIs enable merchants to design custom solutions by integrating advanced features and functionalities developed by other companies.

Determining which API type and protocol suits your company’s unique needs is a long-term business decision.

Learn about API types and protocols and avoid costly mistakes from the get-go.

What is an API?

An API (Application Programming Interface) is a set of protocols and declarations that allow a software solution to interact with and provide services to other software. API is the medium for translating data from one program so that another program can read it.

Organizations use APIs to expose a software product, its capabilities, and data in a machine-readable format. Internal and external clients utilize these resources to build new products and deliver value to the end customer.

For example, a PSP (Payment Service Provider) discloses API endpoints (digital locations) for payment authentication and processing services. Merchants do not need to understand the remote system’s source code; they only need instructions on how to connect their solution to the API endpoint (i.e., integrate with the API).

Note: Find out how to use CCBill’s API to streamline and automate payment flows in your online store. CCBill’s RESTful Transaction API documentation explains how to charge customers using payment tokens.

API Types

A company can utilize different APIs to create unique business solutions and customer-facing applications. Based on the release policy and scope of use, there are four types of APIs.

Public APIs

A public API, sometimes called an open or external API, is intended to be consumed by as many clients as possible. Third-party developers can freely access API documentation and use it to develop and test applications without licensing restrictions.

Organizations openly share their system’s functionalities and data to increase brand awareness or as part of a market penetration strategy.

Internal APIs

Companies use internal APIs to integrate existing applications and systems or build new apps that streamline business processes. They remain in complete control over the API's usage and prevent individuals or applications outside the organization from accessing or communicating with internal systems.

Even though internal APIs are only used within an organization, developers should not compromise on security features, user authorization, or authentication. Companies dealing with sensitive customer information, like payment card data, must ensure that their internal APIs comply with the PCI Data Security Standard.

Partner APIs

Some organizations provide API access to their applications and databases to other companies (partners) to increase ancillary revenue.

A partner API is often used to share sensitive customer information with known business partners, and it incorporates advanced security features and strong user authentication mechanisms.

Partnering companies enter into an agreement with clearly defined API usage terms, costs, and licenses. API providers want to ensure that access is not used in a way that can damage their reputation.

Composite APIs

A complex action like creating a shopping cart order requires several API calls sent to multiple API endpoints.

Composite APIs allow developers to batch several API requests into a single API call and receive a single response in return. Composite APIs are ideal for users who need to collect data from multiple sources and perform a particular task. By reducing the number of API requests and responses, composite APIs can improve application loading times and performance.

Note: Read our article to learn more about API integration and how it can help streamline workflows.

API Architectural Styles (Protocols)

Developers use different technologies and programming languages when developing applications and web services. An API needs to offer a common structure with clear rules and constraints to enable clear communication between two different software solutions.

The four widely used API development protocols or architecture styles include:

• REST
• RPC
• SOAP
• GraphQL

Each format has unique advantages and drawbacks depending on specific use cases and business objectives.

REST

The REST (representational state transfer) architecture style is popular for building APIs consumed by web servers and web apps.

REST relies on a client/server architecture, enabling developers to separate front-end and back-end services. This allows different components to evolve independently over time without compromising system stability.

REST APIs are stateless as receivers cannot keep the session state from a prior request. No information from a call is retained, meaning each session is independent and is understood in isolation.

Web APIs that adhere to REST constraints are called RESTful APIs. RESTful APIs use HTTP requests (methods) and URL-encoded parameters to access API resources. Commonly used RESTful HTTP methods include:  

• POST
• GET
• PUT
• PATCH
• DELETE

RESTful supports many different formats for exchanging and storing data:

• Plain text
• HTML
• YAML
• XML
• JSON

An example of an API request for creating a payment token using CCBill's RESTful API:

var data = JSON.stringify({
  "clientAccnum": 900000,
  "clientSubacc": 0,
  "customerInfo": {
    "customerFname": "Tyler",
    "customerLname": "Thomas",
    "address1": "Woodland Drive",
    "address2": "Apt 21",
    "city": "Tempe",
    "state": "AZ",
    "zipcode": "85281",
    "country": "US",
    "phoneNumber": "5555555555",
    "email": "tthomas@xyz.com",
    "ipAddress": "10.70.60.14'",
    "browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
    "browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "browserHttpAcceptLanguage": "en-US,en;q=0.5",
    "browserHttpAcceptEncoding": "gzip, deflate, br"
  },
  "paymentInfo": {
    "creditCardPaymentInfo": {
      "cardNum": "4473707989493598",
      "nameOnCard": "Tyler Thomas",
      "expMonth": "04",
      "expYear": "2019"
    }
  },
  "subscriptionId": 900000000000000000,
  "timeToLive": 30,
  "validNumberOfUse": 3
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.ccbill.com/payment-tokens/merchant-only");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);

REST is a flexible and scalable architecture style that can support large and dynamic customer bases, making it ideal for public APIs.

RPC

The Remote Procedural Call (RPC) involves sending a request to a remote server and receiving a structured response. RPC is used to initiate actions, unlike REST API, which is used to exchange documents (resources).

RPC APIs are highly structured, and developers can use either JSON or XML to encode requests and bind resources to specific purposes and functions.

RPC APIs are not well suited for intense public consumption. RPC API is best implemented in a microservices-oriented system, where it results in a more tightly coupled and efficient environment.

SOAP

SOAP (Simple Access Object Protocol) is a messaging standard that supports HTTP, TCP, and SMTP communication protocols. Most operating systems utilize these protocols, allowing SOAP-based APIs to power web services regardless of the underlying programing language or platform.

SOAP has a strict structure, and developers are required to encode SOAP messages as XML documents. SOAP messages contain up to four elements:

• Envelope - Mandatory root element that identifies the document as a SOAP message.
• Header - Optional child element used to pass application-related information and add new functionalities.
• Body - Mandatory child element containing the information exchanged with the recipient.
• Fault (error handling) - Optional sub-element of the SOAP body used for reporting errors.

SOAP is ACID compliant and has built-in WS-security and SSL support. Fintech, Telco, and identity management providers use SOAP messages to ensure the security of automated data transmissions.

The SOAP architecture is primarily used for internal and partner API solutions.

GraphQL

GraphQL is a query language and server-side runtime environment for APIs. It aggregates data from multiple sources and retrieves requested data with a single API call.

A GraphQL server contains a predefined schema that describes which queries are allowed, the objects and their fields, and the relationship between data types. A developer can create a GraphQL schema and build an interface around it using any programming language.

The schema allows users to validate potential queries from their editor and discover potential issues before sending a request. Developers can efficiently eliminate potential data format issues by predicting query results ahead of time.

GraphQL does not require the user to apply a specific application architecture and can be used alongside existing REST API. However, it presents a steep learning curve for specialists who previously worked with REST architecture.

How to Choose an API Type?

Merchants need to select the most appropriate API format for their project based on:

• Available resources (financial, technical, and staff).
• The complexity of the data they need to exchange.
• Data security requirements.
• Performance requirements and data exchange speeds.
• The programming languages a protocol supports.
• The development environment in which the solution is being developed.

A basic format, such as RPC, is easier to develop and manage but may not provide enough protection for sensitive customer information merchants typically deal with. An API protocol that offers a high level of security increases development and maintenance costs significantly and forces merchants to hire specialized staff.

The sensible course of action is to apply and test an API protocol in limited use cases and gradually extend it to new use cases before deciding.

Conclusion

APIs allow merchants to develop proprietary business solutions and engage customer-facing apps without spending a fortune on long, drawn-out integrations.

Understanding API types and protocols is an essential first step in making an informed business decision.