API

API vs Web Service

APIs are application interfaces, meaning that one application is able to interact with another application in a standardized way.
Web services are a type of API, which must be accessed through a network connection.

XML [eXtensible Markup Language] is a standardized format for storing and sending data. Similar to HTML, XML stores data by wrapping it in descriptive tags.
JSON [JavaScript Object Notation] is similar to XML in that it also stores and enables you to send data in a standardized format. JSON just uses a different, object-based, methodology for systematically storing data.
HTTP [HyperText Transfer Protocol] is the foundation of transferring data and communications on the internet.

A Web service is a way for two machines to communicate with each other over a network.

An API, or Application Programming Interface, is a set of definitions and protocols that allow one application to communicate with another application.

In general, when we speak about APIs, we are likely speaking about web APIs [APIs that are accessible over the internet]. This is not always the case though. APIs can be exposed through local files (such as a JAR file in a Java program, .H file in C/C++ programs, etc.) to allow two local applications to communicate with each other. This doesn’t require a network as the two applications are communicating within a single device.

As we mentioned in the section about “What is an API?,” not all APIs are accessible over the internet(a network), while Web Services must always be accessed through a network. That’s the difference right there.

All Web Services are APIs, but not all APIs are Web services.

Main types of Web APIs

There are four main types of APIs:

Open APIs: Also known as Public API, there are no restrictions to access these types of APIs because they are publicly available.

Partner APIs: A developer needs specific rights or licenses in order to access this type of API because they are not available to the public.

Internal APIs: Also known as Private APIs, only internal systems expose this type of API. These are usually designed for internal use within a company. The company uses this type of API among the different internal teams to be able to improve its products and services.

Composite APIs: This type of API combines different data and service APIs. It is a sequence of tasks that run synchronously as a result of the execution, and not at the request of a task. Its main uses are to speed up the process of execution and improve the performance of the listeners in the web interfaces.

Web service APIs

Apart from the main web APIs, there are also web service APIs:
REST
XML-RPC
JSON-RPC
SOAP

API Architectures and Protocols

An API protocol defines the rules for API calls: it specifies accepted data types and commands. Different API architectures specify different protocol constraints.

REST

REST (short for ‘Representational State Transfer’) is a web services API. REST APIs are a key part of modern web application development and massive applications like Netflix, Facebook, and many others.
REST is a very popular web API architecture. To be a REST API, an API must adhere to certain architectural constraints, or principles, including:
Client-server architecture
Statelessness
Cacheability
Layered system

The API accepts and returns HTTP (not enabled by default) or HTTPS messages that contain JSON or XML documents.

A REST request from the client to the server usually consists of the following components:
URL Path [https://api.example.com/user]
HTTP Method [GET, PUT, POST, PATCH, DELETE]
Header – (optional) additional information that the client needs to pass along in the request such as Authorization credentials, Content-Type of the body, User-Agent to define what type of application is making the request, and more]
Parameters – (optional) variable fields that alter how the resource will be returned.
Body – (optional) contains data that needs to be sent to the server.

RPC

An RPC (Remote Procedure Call) APIs is the oldest and simplest types of API. The goal of an RPC is for the client to execute code on a server. The major benefit of RPC APIs is they make it easier for developers to create applications involving multiple programs or services.
There are two main types of RPC APIs:
XML-RPC
JSON-RPC

SOAP

A SOAP (Simple Object Access Protocol) API is like REST in that it’s a type of Web API.
The SOAP specification includes:
The processing model
Extensibility model
Protocol binding rules
Message construct

Note that it is possible to build a RESTful API while using SOAP protocols, although the two are usually considered to be competing standards.

SOAP only allows XML, which is not nearly as straightforward to create.

Differences between SOAP and REST

API Data Formats

Common Industry Formats

We’re going to separate the most common industry languages of the day into four general categories:
Direct Data Formats (JSON, XML, YAML): formats that support the sharing of data directly for use in other systems, are best used in B2B or public-facing API implementations
Feed Data Formats (RSS, Atom, SUP): formats that serialize changes and update users to these changes, are best used in subscription industries such as blogs, video sharing, and social media
Manipulation Data Formats (KML, PDF): formats in which data is wrapped for sharing in document form, are best used in design and communication oriented industries
Database Data Formats (CSV, SQL): formats in which data is categorized and stored in database formats for interpretation, are best used in analytic dependent or long-term data utilization implementations

Direct Data Formats

Direct Data Formats are designed to handle data directly between machines. These languages are often called machine readable, as they tend to be dense and compact. This means they are great for machine-machine integration, and/or manipulation with other APIs.
Direct data formats are best used when additional APIs or services require a data stream from your API in order to function. The three most common formats in this category are JSON, XML, and YAML.

JSON
JSON (JavaScript Object Notation) is a wonderful format when it comes to handling client-side scripting, and is a generally faster counterpoint to other options such as XML. In many ways, it might not be as powerful or widely used as other choices, but it supports many features that make its adoption a powerful choice.

XML
XML (EXtensible Markup Language) likewise has some large advantages. While it is all but ubiquitous, with a large install base, its greatest strength may be its greatest weakness. It’s the “kitchen sink” of formats, throwing in everything it possibly can.

YAML
YAML (YAML Ain’t Markup Language) is “is a human friendly data serialization standard for all programming languages.” Where JSON is lightweight with a somewhat lax feature set, and XML is verbose but often a bit cumbersome, YAML is easy to read, lightweight, and generally “middle of the road”. While it’s classified as a direct data format due to how it’s used to parse configuration settings and relational queries, many systems use it as a basic flat database.

Differences between JSON and XML