Integrating APIs - the Types and Processes involved

API integration connects the parts of almost every modern product. An API works like a contract between systems: it defines what one side can request and what the other side returns, and that contract shapes the architecture. That is why APIs should be planned from the start of a project, during the Project Discovery Phase, with a contract model that allows for changes, such as time and material. We integrate APIs for different purposes: to let the backend communicate with the frontend, or to extend a product with third-party services, such as geolocation services for finding directions to a business.

This article covers API types by policy and by use, the differences between SOAP and REST and when to use each, and two ways to build APIs: integration-first and API-first.

Planning a discovery phase for a project with API integrations? Contact us.

APIs by Policies

The policy defines who can use an API and which data or functions it exposes.

Private APIs

Private APIs are for internal use within a company. We build them to connect existing IT systems or applications, and the developer or the client keeps full control over them. A typical example is the backend passing data from the database to the frontend to display on screen: the communication stays between the frontend and the backend.

Partner APIs

Partner APIs are shared only with business partners who have signed an agreement with the publisher. They are typically used to integrate software between two companies. The publisher can earn extra revenue by giving partners access to its data or functions, while still controlling how they are used and checking that partner applications give users a decent experience.

Public APIs

Public APIs, also called external or developer-facing APIs, are available to any third-party developer. A well-run public API programme can raise brand awareness and bring in extra income.

Public APIs can be open (free) or commercial. With an open API, all features are public and come without restrictive terms: anyone can build and test an application on it without explicit approval from the provider or licence fees, and its documentation is openly available.

Commercial APIs are paid for by subscription or on a pay-as-you-go basis. Many publishers offer free trials so developers can evaluate an API before subscribing.

Go Wombat designs and integrates APIs. Contact us to discuss your project.

APIs by Uses

Database APIs

Database APIs connect an application to a database management system. Backend developers use them to write queries that read data or change tables. Some database APIs let you write the same queries for different databases, proprietary or open-source.

Operating system APIs

These APIs define how applications use the resources and services of an operating system. Every OS has its own set, for example the Windows API or the Linux API.

Remote APIs

Remote APIs define how applications running on different machines interact: one application accesses resources located outside the device that requests them. Because these applications are connected over a network, usually the internet, most remote APIs follow web standards. Java Database Connectivity (JDBC) and Java Remote Method Invocation (RMI) are two examples.

Web APIs

Web APIs are the most common class. They transfer machine-readable data and functionality between web-based systems in a client-server architecture, usually carrying requests from web applications and responses from servers over HTTP.

Contact us if you need advice on which APIs your project needs.

Features of APIs

Specifications

The two best-known approaches to web APIs are SOAP and REST.

SOAP

SOAP is the older of the two. The name originally stood for Simple Object Access Protocol, but the W3C's SOAP 1.2 specification (2003) states that it is no longer an acronym. SOAP relies on XML and, together with XML schemas, defines a strongly typed and fairly rigid messaging framework: the XML structure explicitly defines every request and response, and each input parameter is bound to a type, such as an integer, a string or a complex object.

Below is an example of a SOAP message that requests the price of an item in stock.

The frontend requests the price of the item through the API, and the backend returns the price through the API.

SOAP messages carry a lot of XML markup, so SOAP transfers considerably more data than REST for the same request.

SOAP is a protocol with a formal specification. SOAP services are often described with WSDL (Web Services Description Language), a separate W3C specification that defines what a web service does and where it is located. SOAP can also be used without WSDL.

Every SOAP message is written in XML. REST, by contrast, is an architectural style rather than a protocol, and it works with several data formats.

REST

REST (Representational State Transfer) is an architectural style that relies on a stateless communication protocol, most commonly HTTP. REST APIs can exchange data in XML, YAML or any other machine-readable format, but JSON is the most widely used.

REST is resource-oriented: URLs name resources (nouns) and HTTP methods define the actions on them (verbs). This makes REST data-driven, while SOAP is function-driven. The terms RESTful APIs and RESTful web services are used interchangeably.

We use REST APIs because they are more flexible to work with.

Web APIs that comply with REST constraints are called RESTful APIs. They work with resources through HTTP methods, mainly GET, POST, PUT, PATCH and DELETE, plus HEAD and OPTIONS. CONNECT and TRACE are HTTP methods too, but they are used for proxy tunnels and diagnostics, not for working with resources in a REST API.

Here is an example of a GET request to a REST API that returns JSON.

It shows how the frontend of a web page requests news items from the backend through an API.

The endpoint "example.com/news/" returns a list of news items. When the frontend sends a GET request to it, the backend returns JSON:

The frontend places this data in the layout, so the user sees a list of news titles. Each title links to the endpoint of its detail page. When the user clicks a title, the frontend sends another request to that endpoint, and the backend returns the details of the news item, again in JSON:

The frontend again places the data according to the design.

A REST response in JSON carries considerably less data than a SOAP message, which makes it simpler to code and more efficient to transfer.

When to use REST and when to use SOAP

SOAP and REST suit different situations. These are the main factors to consider.

REST

REST messages are smaller, so REST uses less bandwidth. Choose it when network bandwidth is limited.

Statelessness

REST is stateless: the server does not keep session state between requests, and each request carries everything needed to process it. This does not rule out multi-step processes such as an online shop checkout. The cart is stored as a resource (for example, /carts/{id}), and the client refers to it in each request. Payment and e-commerce APIs are commonly built this way; the Stripe API, for example, is organised around REST, including payments and checkout.

Caching

Clients often request the same data many times, which adds traffic to and from the server. REST suits this well: responses to GET requests can be stored in an intermediate cache, so frequently requested data is served without contacting the server.

Ease of coding

REST services are usually faster to build and simpler to implement than SOAP services.

SOAP

Some processes need reliability and security built into the messages themselves. SOAP has established extensions for this, such as WS-Security from OASIS. These features come from the extensions, not from SOAP 1.2 itself, which has been a W3C Recommendation since 2003.

When the client and server need a formal agreement on the exchange format, SOAP provides a strict specification for it.

For example, a payment service may accept only a strictly defined message with the cart item name, unit price and quantity. If a partner already exposes such a service with a WSDL contract, as many banking and government systems do, SOAP is the natural choice.

Stateful operations

If an application must keep state across requests, for example to run a multi-step transaction, SOAP can use the WS-* extensions, such as WS-ReliableMessaging and WS-AtomicTransaction. The SOAP 1.2 processing model itself does not maintain state between messages.

The Role of APIs

APIs let a company add new services, such as payments or delivery tracking, without rebuilding its product. That makes it easier to change quickly.

The benefits

An API is a gateway to a company's digital assets. It lets the company build new customer-facing products faster, open new revenue channels and extend the product later.

These benefits depend on how well the APIs and integrations are designed and implemented.

Call us to discuss your API project.

Integration-first vs. API-first

Companies build APIs, RESTful or otherwise, in one of two ways: integration-first or API-first.

Integration-first is a bottom-up, back-to-front approach: the integration logic is built first on top of backend services, and the resulting composite services are then exposed to users as managed APIs.

With API-first, the API is designed first and then implemented together with the integration logic.

An integration-first approach

Based on the project requirements, the backend team builds an integration layer that exposes the existing systems.

The backend team exposes the backend services through REST APIs, and the frontend team connects the web and mobile applications to them.

Some features are hard to implement with the existing APIs, so the frontend team raises a change request (CR) for the backend team.

The backend team updates the backend and the API to support the new capability.

This repeats for several iterations until both teams agree on the right API for each feature.

This can push up timelines and costs: the teams communicate less, and design flaws surface late in the project.

An API-first approach

API-first is more collaborative: the frontend and backend teams design the APIs together.

Involving the frontend team early brings the user experience into the API design, and developers do not have to wait for separate design phases.

Frontend and backend work can run in parallel, because the frontend team can develop against a mock backend.

This reduces the miscommunication that leads to late changes in the backend and APIs, along with the delays and budget overruns they cause.