API

Definition
 An API, or Application Programming Interface, is a set of rules and protocols
that allows different software applications to communicate and exchange
data with each other. Think of it as a messenger between two applications,
enabling them to interact and share information.
 APIs are the building blocks for the today’s websites in which heavy data is
transferred from the client to server and vice versa.
 APIs are essentially a contract or interface that defines how one software
application can interact with another.

How it works:
When one application needs to access data or functionality from another, it
sends a request through the API, which then translates that request and passes it
to the target application. The target application processes the request and sends
back a response, which the original application receives through the API.
APIs work in a simple step-by-step process:
 Request: A client (user) sends a request through the API's URI (Uniform
Resource Identifier).
 Processing: The API forwards the request to the server.
 Response: The server processes the request and sends the response back to
the API.
 Delivery: The AsPI returns the server's response to the client.

Examples:
 Web development: APIs allow web applications to communicate with
servers and databases to retrieve and display information.
 Mobile apps: APIs enable mobile apps to access data and functionality from
cloud services or other applications.
 IoT devices: APIs facilitate communication between IoT devices and other
systems, allowing them to share data and control functionality.
 Third-party services: APIs allow different applications and web services to
work together and share data.
 Microservices: APIs are used to build microservices architectures.

Benefits:
 Reusability: APIs allow developers to reuse existing functionality and
data instead of building everything from scratch.
 Integration: APIs enable different applications and systems to integrate
and work together seamlessly.
  Innovation: APIs facilitate the creation of new business models, products,
and services by enabling easy integration and rapid innovation.
 Scalability: APIs can help developers build scalable applications that can
handle large amounts of traffic and data.

***What is a URI?
A Uniform Resource Identifier (URI) is a string of characters used to identify a
resource on the internet(whether it's a logical or physical resource). A URI can be
broken down into several components:
 Scheme: Specifies the protocol (e.g., https, ftp).
 Authority: Identifies the domain (abstractapi.com).
 Path: Specifies the resource location (/v1/).
 Query Parameters: Provide additional information (?
[email protected]).
 Fragment: Points to a specific section within a resource (rarely used in
APIs).
For example, in the URI:
 https://emailvalidation.abstractapi.com/v1/?
[email protected]
 https is the scheme.
 emailvalidation.abstractapi.com is the authority.
 /v1/ is the path.
 [email protected] is the query parameter.

‍***URI vs. URL: Clarifying the Difference

A URL (Uniform Resource Locator) is a specific type of URI that not only identifies
a resource but also provides a means to locate it.
Simple Analogy of URI vs. URL
Think of a URI as a person’s name—it identifies them uniquely. A URL, on the
other hand, is like their home address—it tells you where to find them.
While URLs (Uniform Resource Locators) are a type of URI that also specifies a
resource's location or address, URIs are more general. A URI can be a name or an
address, while a URL is specifically an address.
Thus, all URLs are URIs, but not all URIs are URLs. An example of a URI that is not
a URL could be a mailto: URI (mailto:[email protected]), which does
not specify a location but still identifies a resource.
What is URI API?
An API (Application Programming Interface) uses URIs to identify specific
resources or functionalities. Every API request includes a URI that tells the server
what data or action is required.
For example, when an application requests user data, the API call might look like
this:
 GET https://api.example.com/users/123
 The URI /users/123 specifies that the API should return information about
user 123.
How APIs Use URIs
APIs use different HTTP methods with URIs to perform actions:
 GET /users/123 → Retrieve user details.
 POST /users → Create a new user.
 PUT /users/123 → Update user 123’s details.
 DELETE /users/123 → Remove user 123.
Common API URI patterns include:
 /users/{user_id} → Retrieve a specific user.
 /products?category=electronics → Filter products by category.
 *** NOTE: The question mark ("?") is used to delimit the boundary
between the URI of a queryable object, and a set of words used to express
a query on that object.
 /articles/{article_id}/comments → Access nested resources like
comments under an article.
Emphasizing Resource Identification
Think of a URI as a home address for data. Without the correct URI, an API won’t
know where to retrieve or send information, making it a fundamental part of API
communication.

***Microservices Vs APIs
Microservices and APIs are related but distinct concepts in software
development.
 Microservices are an architectural style where an application is broken
down into smaller, independent services. APIs, on the other hand, are the
protocols and rules that allow these services, or any other software, to
communicate and exchange data.
 Microservices often use APIs to expose their functionality to other services
or external clients.
Microservices use APIs:
 Microservices often use APIs to expose their functionality to other
microservices or external clients, allowing them to interact and exchange
data.

APIs are not exclusive to microservices:

APIs can be used to communicate between any software components, not
just microservices.


Microservices:
Microservices architecture is a software development approach where an
application is built as a collection of independent, small services, each
with its own functionality and database.

Key Characteristics of Microservices:

 Independent Services: Each microservice is a distinct, self-contained
unit with its own codebase, database, and deployment process.
 Decentralized Governance: Different teams can independently develop,
deploy, and manage microservices.
 Loose Coupling: Microservices are designed to be loosely coupled,
meaning they depend on each other as little as possible.
 Independent Deployability: Each microservice can be deployed
independently, allowing for faster releases and easier upgrades.
 Scalability: Individual microservices can be scaled independently to
handle peak loads, while the whole application remains stable.
 Fault Isolation: If one microservice fails, it shouldn't affect the entire
application.
 API-Driven Communication: Microservices communicate with each
other using APIs, often RESTful APIs.

Benefits of Microservices:
 Increased Agility: Easier to make changes, deploy new features, and
respond to evolving business needs.
 Faster Development Cycles: Independent development and
deployment allow for quicker iteration and innovation.
 Better Scalability: Individual services can be scaled independently to
handle varying workloads.
 Improved Fault Tolerance: If one service fails, others can continue to
operate.
 Resource Efficiency: Only necessary services are scaled, reducing
infrastructure costs.
  Enhanced Collaboration: Different teams can work on different
microservices simultaneously.

Challenges of Microservices:
 Increased Complexity: Managing a distributed system of microservices
can be complex.
 Data Consistency: Maintaining data consistency across multiple
databases can be challenging.
 Service Discovery: Finding and connecting to other services in a
distributed environment can be complex.
 Monitoring and Logging: Centralized monitoring and logging can be
challenging for distributed systems.
 Debugging: Debugging failures across multiple services can be more
complex.

Types of APIs:
APIs are broadly categorized based on their purpose, audience, and underlying
architecture. Commonly, they are classified as Open APIs, Partner APIs, Internal
APIs, and Composite APIs, and are further distinguished by their protocol (like
REST, SOAP, or GraphQL). Additionally, APIs can be categorized by their
architecture, such as monolithic or microservices APIs.
Here's a more detailed breakdown:

By Audience - Web API

Web API Is simply an API for the web. It is an API that can be accessed using the HTTP protocol.

 Open APIs: Publicly available to anyone, often used for building

applications that interact with external services (e.g., Google Maps API).
 Partner APIs: Designed for specific organizations or partners, allowing
them to share business logic and functionalities (e.g., WhatsApp Business
API).
 Internal APIs (Private APIs): Used within a single organization, enabling
communication between different internal systems.
 Composite APIs: Combine multiple underlying APIs into a single
interface, streamlining access to complex data or processes.

By Architecture:
 Monolithic APIs: Single, coherent codebase providing access to a
complex data source.
 Microservices APIs: APIs that are built using a microservices
architecture, where each API provides a specific functionality.
By Protocol:
 REST (Representational State Transfer): A popular type of API that
focuses on using HTTP methods to interact with resources.
 SOAP (Simple Object Access Protocol): A protocol that uses XML
messages for communication between applications.
 GraphQL: A query language for APIs that allows clients to specify the
exact/only data they need, improving efficiency.
 RPC (Remote Procedure Call): A protocol that allows procedures to be
called on a remote server as if they were local.
 Webhooks: A type of API that allows applications to receive real-time
updates from other applications.

REST API
REST stands for Representational State Transfer, and follows the constraints of
REST architecture allowing interaction with RESTful web services. It defines a set
of functions (GET, PUT, POST, DELETE) that clients use to access server data. The
functions used are:
 GET (retrieve a record)
 PUT (update a record)
 POST (create a record)
 DELETE (delete the record)
Its main feature is that REST API is stateless, i.e., the servers do not save clients'
data between requests.

Features of REST API:

 Statelessness:
REST APIs are stateless, meaning each request from a client to a server contains
all the necessary information, and the server doesn't store any client’s
context/data between requests.
 Client-Server Architecture:
REST APIs operate on a client-server model, where the client (e.g., a web
application or mobile app) sends requests to the server, and the server responds
with the requested data or resources.
 Uniform Interface:
REST APIs use a uniform interface, meaning they follow consistent standards and
conventions for accessing and manipulating resources, typically using HTTP
methods (GET, POST, PUT, DELETE).
 Resources:
In REST, data and functionality are treated as resources, which are identified by
unique URLs (Uniform Resource Locators).

How it Works:
1. Client Request:
A client application sends a request to a RESTful API using a specific HTTP
method (e.g., GET to retrieve data, POST to create data, PUT to update data,
DELETE to delete data).
2. Server Response:
The server processes the request and returns a response, typically in a
standard format like JSON or XML, along with an HTTP status code indicating
the success or failure of the request.
3. Data Exchange:
The client application then uses the received data to update its user interface or
perform other actions.

Benefits of RESTful APIs:

*** A RESTful API is a type of application programming interface (API) that follows
the architectural style of Representational State Transfer (REST) RESTful APIs are
known for their statelessness, scalability, and use of standard HTTP methods.
 Simplicity:
REST APIs are relatively easy to understand and implement, making them a
popular choice for web and mobile application development.
 Scalability:
Due to their stateless nature and lightweight protocols, REST APIs are highly
scalable and can handle large volumes of traffic.
 Flexibility:
REST APIs are flexible and can be used to build a wide variety of applications and
services.
 Interoperability:
REST APIs are designed to be interoperable, meaning they can be used to
communicate with different systems and applications.
 Common Web Technologies:
REST APIs use common web technologies like HTTP, making them easy to
integrate with existing web infrastructure.

SOAP API
SOAP, or Simple Object Access Protocol, is a messaging protocol. It allows the
exchange of structure information without any platform. Soap uses the XML data
format due to the complexity. It is mostly used for complex systems with strict
standards ensuring security and reliability.
Key Concepts
 SOAP is a protocol as it has some strict rules for data format and
communication.
 It manages the records and maintains the state between the requests.
 SOAP relies on SSL and WS-Security for secured communication.
 SOAP works with the XML data format to handle the complex data

SOAP vs. REST

 SOAP is a protocol for communication between applications. REST is an architecture style for
designing communication interfaces design.
 SOAP API exposes the operation. REST API exposes the data.

SOAP REST

SOAP (Simple Object Access

REST (Representational State Transfer) is
Protocol) is a protocol with
a set of guidelines (architectural
specific requirements like XML
style) offering flexible implementation
messaging

Heavier and needs more

Lightweight and needs less bandwidth
bandwidth

It inherits security from the underlying

It defines its own security
transport

It permits XML-based data It permits different data formats such as

format only plain text, HTML, XML, JSON, etc.

SOAP calls cannot be cached REST calls can be cached

Also, the major difference is that SOAP cannot make use of REST whereas REST
can make use of SOAP.
Stateful vs Stateless API
In API design, a stateless API treats each request as independent, while
a stateful API maintains client state across multiple requests.
Stateless APIs are generally easier to scale and are common in microservices,
while stateful APIs are useful for applications requiring persistent sessions or
user context.
Here's a more detailed breakdown:

Stateless APIs:
 Definition:
Each request is treated as a new, isolated transaction, without the server storing
any information about previous requests.
 Scalability:
Stateless APIs are highly scalable because any server can handle any request, as
it doesn't rely on the state of previous requests.
 Resource Utilization:
Stateless APIs generally require fewer resources as they don't need to store
session data.
 Examples:
***Many REST APIs are designed to be stateless.
 Advantages:
 Scalability: Easier to scale horizontally by adding more servers.
 Simplicity: Simpler to implement and maintain.
 Fault Tolerance: If a server fails, the client can simply re-submit
the request to another server.
 Disadvantages:
 No Context: Cannot maintain user context or session data across
multiple requests.
 Increased Load: Each request might require the client to re-transmit
all necessary information.

Stateful APIs:
 Definition: The server maintains information about the client's state or
session between requests.
 Scalability: Stateful APIs can be more difficult to scale because each
client is tied to a specific server that stores its session data.
  Resource Utilization: Stateful APIs require more resources to store and
manage session data.
Examples: Web applications with login sessions or shopping carts.
 Advantages:
o Context: Maintains user context and session data across multiple
requests.
o Personalized Experience: Can provide a more personalized user
experience.
 Disadvantages:
o Scalability Challenges: Can be difficult to scale horizontally.

o Complexity: More complex to implement and maintain.

o Fault Tolerance: If a server fails, the client might lose their session
data.

Choosing Between Stateless and Stateful APIs:

 Stateless APIs
are generally preferred for applications where each request is independent and
scalability is a primary concern.
 Stateful APIs
are useful when maintaining user context or session data is required, such as in
web applications with login sessions or shopping carts.
 Hybrid Approaches:
Some applications might use a combination of both stateless and stateful
components.

API Error Codes

Common API errors include those related to the request (client-side errors like
400 Bad Request and 401 Unauthorized) and server-side issues (500 Internal
Server Error, 502 Bad Gateway). Other errors involve resource unavailability (404
Not Found, 503 Service Unavailable), and security or authorization problems (403
Forbidden, 401 Unauthorized).

Client-Side Errors (4xx):

 400 Bad Request: The client's request is malformed or cannot be
processed.
  401 Unauthorized: The client is not authenticated or does not have valid
credentials.
 403 Forbidden: The client is not authorized to access the requested
resource.
 404 Not Found: The requested resource cannot be found on the
server. The server cannot locate the specific resource (API endpoint or
data) that was requested. This usually indicates an issue with the client's
request, such as a mistyped URL or a missing resource on the server.
o The 404 error is an HTTP status code (4xx class) that indicates a
client-side error.
o Resource Not Found:
 It means the server has processed the request but couldn't
find the requested resource within its scope.
o Common Causes:
 Incorrect URL: The client might have provided an incorrect
or misspelled API endpoint URL.
 Missing Resource: The requested API endpoint or data
might have been removed or moved from the server.
 Misconfigured Gateway: In API gateways, the 404 can
occur if the gateway can't route the request to the correct
backend API.
*** API EndPoint
An API endpoint is a specific URL that a client application can use to request a
particular service or data from a server. It's the address where the API "lives" and
where requests are sent.
Consider a weather API. A client application (like a weather app on your phone)
might use these endpoints:
 https://api.example.com/weather/current: This endpoint would return the
current weather conditions.
 https://api.example.com/weather/forecast: This endpoint would provide a
weather forecast for a specific location.
*** *** ***
 Permission Issues: In some cases, the user might not have the
necessary permissions to access a specific API endpoint, leading to a 404.
 405 Method Not Allowed: The HTTP method used in the request is not
supported for the resource.
 429 Too Many Requests: The client has exceeded the rate limit.

Server-Side Errors (5xx):

 500 Internal Server Error: A generic error indicating a problem on the
server. "Internal Server Error," means the server encountered a problem
while processing your request, preventing it from fulfilling the request.
  502 Bad Gateway: The server acting as a gateway received an invalid
response from another server.
 503 Service Unavailable: The server is currently unable to handle the
request.
 504 Gateway Timeout: The server timed out while waiting for a
response from an upstream server.

Other Common Errors:

 408 Request Timeout: The client's request timed out before the server
could respond.
 418 I'm a Teapot: An unusual error code, often used for demonstration
purposes.
 Error 301, or "Moved Permanently," is an HTTP status code indicating that
a web page has been permanently moved to a new URL.

Understanding Error Codes:

 4xx errors: typically indicate issues with the client's request, while 5xx
errors point to problems on the server's side.
 Understanding the specific error code can help developers diagnose the
problem and implement appropriate error handling.

API Successful Codes

In APIs, a "success code" generally refers to an HTTP status code in the 200-299
range, indicating that the request was successfully received and processed. The
most common success code is 200 OK, which means the request was successful
and the server returned the requested data. Other success codes include 201
Created, 204 No Content, and 206 Partial Content.
Here's a more detailed look at some common success codes:
 200 OK:
The most common success code, indicating the request was successful and the
server returned the requested data.
 201 Created:
This code indicates the request was successful and a new resource has been
created on the server.
 204 No Content:
This code signifies that the request was successful, but the server doesn't need
to return any data in the response body.
 206 Partial Content:

Used when the client requests only part of a resource, and the server fulfils that partial
request.