API Development Essentials: REST, SOAP, GraphQL Explained

REST API
Ankit Raj
Software Engineer

Agenda
● What is an API?
● How Do APIs Work?
● Types of APIs
● API Architecture Styles
● REST API Example
● HTTP Methods in REST APIs
● Benefits of Using APIs

What is an API?
❏ Definition: An API (Application Programming Interface) is a set of rules that allows
software programs to communicate with each other.
❏ Analogy: Think of an API as a waiter who takes your order (request) to the kitchen (the
server) and delivers the food (response) back to you.
❏ Key Components:
❏ Request: What you ask for.
❏ Response: What you receive.
❏ Endpoint: The specific URL where the API request is sent.

How Do APIs Work?
❏ Request:
❏ A user or application makes a request to the API through a URL (called an endpoint).
❏ This request includes:
❏ URL: The endpoint, e.g., https://api.example.com/users.
❏ Method: Such as GET (retrieve data), POST (send data), PUT (update data), or DELETE.
❏ Headers: Information like authentication tokens.
❏ Parameters: Extra data, like user IDs, filters, etc.
❏ Analogy: This is like placing an order in a restaurant where you specify what you
want.

How Do APIs Work?
❏ Processing on the Server:
❏ The server processes the request. It may:
❏ Query a database.
❏ Perform calculations.
❏ Communicate with other services.
❏ Analogy: The server acts like the kitchen in the restaurant, preparing the order
based on your request.

How Do APIs Work?
❏ Response:
❏ The API sends back a response in a specific format (usually JSON or XML).
❏ The response includes:
❏ Status Code: Indicates success (200), an error (404, 500), etc.
❏ Data: The requested information or confirmation of the action.
❏ Analogy: The waiter brings back your meal (the data).

A diagram showing the request, API server, and response process.

Types of APIs
● Open APIs (Public APIs)
● Internal APIs (Private APIs)
● Partner APIs
● Composite APIs

1. Open APIs (Public APIs)
Definition: Open APIs are publicly available to developers and other users with minimal
restrictions. They are intended to be used by external developers to access certain
functionality or data from a system.
Characteristics:
❏ Accessible: Anyone can register and start using the API with little to no approval.
❏ Use Case: Often used for third-party integrations or to promote the use of a service (e.g., social
media APIs).
❏ Examples:
❏ Twitter API: Allows developers to retrieve tweets, user profiles, and other data.
❏ Google Maps API: Provides geographical data, maps, directions, and location services.

1. Open APIs (Public APIs)
Characteristics:
❏ Benefits:
❏ Wider Reach: Helps companies or platforms grow by enabling developers to create apps that extend their
services.
❏ Fosters Innovation: External developers can create new apps and tools.
❏ Challenges:
❏ Security Concerns: Because they are open, they can be prone to misuse.
❏ Rate Limiting: Due to high demand, APIs often limit the number of requests a developer can make in a given
timeframe (to avoid overloading servers).

2. Internal APIs (Private APIs)
Definition: Open APIs are publicly available to developers and other users with minimal
restrictions. They are intended to be used by external developers to access certain
functionality or data from a system.
Characteristics:
❏ Accessible: Anyone can register and start using the API with little to no approval.
❏ Use Case: Often used for third-party integrations or to promote the use of a service (e.g., social
media APIs).
❏ Examples:
❏ Twitter API: Allows developers to retrieve tweets, user profiles, and other data.
❏ Google Maps API: Provides geographical data, maps, directions, and location services.

2. Internal APIs (Private APIs)
Characteristics:
❏ Benefits:
❏ Efficiency: Helps internal teams work faster by automating tasks and data exchange between internal systems.
❏ Cost-Effective: Reduces the need for manual intervention or repetitive tasks across departments.
❏ Challenges:
❏ Maintenance: Requires ongoing internal development and management.
❏ Security: Even though it's internal, these APIs still need to be secured against potential insider threats or
misconfigurations.

3. Partner APIs
Definition: Partner APIs are shared with specific third-party business partners to allow
integration between systems. They are not open to the public but are available to specific
external users, usually with special access or a business agreement.
Characteristics:
❏ Selective Access: Unlike open APIs, only authorized partners can use them.
❏ Use Case: Used in B2B (business-to-business) scenarios, where two companies collaborate and
need to share data or services securely.
❏ Examples:
❏ Payment Gateway Integration: A partner API used by a payment provider (like Stripe) to allow e-commerce
sites to process transactions.
❏ Airline/Travel Partner APIs: Travel agencies may use partner APIs to integrate with airlines, hotels, and car
rental services to offer customers a comprehensive booking experience.

3. Partner APIs
Characteristics:
❏ Benefits:
❏ Stronger Relationships: Helps foster trusted partnerships by enabling secure, shared access to resources.
❏ Custom Solutions: Allows more tailored integrations between the companies' services.
❏ Challenges:
❏ Limited Access: Requires a formal partnership, so not everyone can use it, which may limit innovation.
❏ Higher Complexity: Integration between two companies often involves more negotiations and complexity
compared to open APIs.

4. Composite APIs
Definition: Composite APIs allow a client to access multiple endpoints or services in a
single API call. This is particularly useful when you need to fetch data from multiple
services or databases at once.
Characteristics:
❏ Single Request, Multiple Responses: Instead of calling multiple APIs separately, you can combine
them into one call.
❏ Use Case: When a client needs to collect data from multiple sources, such as pulling user details
from one API and their transaction history from another.
❏ Examples:
❏ E-commerce Application: A composite API might fetch user information, product listings, and cart details in
one API call instead of making three separate requests.
❏ Financial Data Retrieval: A financial services application might use a composite API to retrieve balance, recent
transactions, and interest rates all at once.

4. Composite APIs
Characteristics:
❏ Benefits:
❏ Efficiency: Reduces the number of network calls, leading to faster response times and less overhead.
❏ Better Performance: Optimizes data retrieval, especially for mobile apps or limited-bandwidth scenarios.
❏ Challenges:
❏ Complex Error Handling: When one part of the composite request fails, it can affect the entire response.
❏ Increased Complexity: Requires careful design to manage multiple dependencies in one API call.

API
Architecture
Styles
● REST (Representational State
Transfer)
● SOAP (Simple Object Access
Protocol)
● GraphQL

1. REST (Representational State Transfer)
❏ Origin:
❏ History: REST was introduced in the early 2000s by Roy Fielding in his doctoral dissertation in 2000
at UC Irvine. REST emerged as a response to the complexities of older, more rigid communication
protocols like SOAP. The goal was to create a simple, scalable way for systems to interact over HTTP.
Key Principles:
❏ Statelessness: Each request from the client to the server must contain all the information the
server needs to fulfill the request. The server does not store any information about previous
requests (no session data).
❏ Client-Server Model: The client and server operate independently of each other. The client doesn’t
need to know the server’s inner workings, and vice versa.

Key Principles:
❏ Resource-Oriented: Everything in a REST API is considered a resource, which can be manipulated
using standard HTTP methods (GET, POST, PUT, DELETE).
❏ Uniform Interface: REST APIs must follow standard rules for interacting with resources (like using
HTTP verbs) to ensure simplicity and consistency.
HTTP Verbs Used in REST:
❏ GET: Fetch data from the server.
❏ POST: Create new resources.
❏ PUT/PATCH: Update existing resources.
❏ DELETE: Remove resources.

Data Formats: REST APIs can return data in various formats like JSON, XML, HTML, or
plain text, but JSON is the most commonly used format due to its simplicity and wide
adoption.
Advantages of REST: Everything in a REST API is considered a resource, which can be
manipulated using standard HTTP methods (GET, POST, PUT, DELETE).
HTTP Verbs Used in REST:
❏ Simplicity: REST APIs are easy to use and well-suited for modern web and mobile applications.
❏ Scalability: REST is stateless, so servers can handle more requests without tracking session data,
making it scalable.
❏ Caching: REST APIs support caching, which can improve performance by reducing the number of
requests made to the server.

Disadvantages of REST:
❏ Over-fetching/Under-fetching: REST can sometimes retrieve too much or too little data for the
client's needs, leading to inefficiency.
❏ Not Ideal for Real-Time Applications: REST isn’t designed for real-time communication, which can
be a drawback for applications like chat systems or stock trading platforms.

2. SOAP (Simple Object Access Protocol)
❏ Origin:
❏ History: SOAP was developed by Microsoft and IBM in the late 1990s. It predates REST and was
originally intended to facilitate communication between systems over the internet using XML-
based messaging. SOAP gained popularity in the early 2000s, particularly in enterprise
environments that required strict security and reliability.
Key Principles:
❏ Protocol-based: Unlike REST, which is an architectural style, SOAP is a strict protocol. It follows a
set of formal rules for sending messages between services.
❏ XML-based: SOAP relies exclusively on XML (Extensible Markup Language) to format data, which is
more verbose than JSON but supports complex data types and structures.

Key Principles:
❏ Transport-independent: While SOAP is most commonly used over HTTP, it can be used with other
protocols like SMTP (for emails) or even JMS (Java Message Service).
❏ WS-Security: SOAP includes built-in standards for security, such as encryption and digital
signatures, which makes it highly secure and suitable for applications that handle sensitive data
(e.g., banking, healthcare)
SOAP Message Structure:
❏ Envelope: Defines what is in the message and how to process it.
❏ Header (Optional): Contains meta-information about the message (e.g., authentication).
❏ Body: Contains the actual message or data to be transmitted.
❏ Fault: Used for error handling and returning detailed error messages when something goes

Advantages of SOAP
❏ Security: REST APIs can return data in various formats like JSON, XML, HTML, or plain text, but
JSON is the most commonly used format due to its simplicity and wide adoption.
❏ Reliability: SOAP has built-in support for ACID transactions (Atomicity, Consistency, Isolation,
Durability) and message-level security, ensuring reliable delivery even in distributed systems.
❏ Standardized: SOAP has strict standards that ensure messages are processed in the same way
across different systems, ensuring compatibility in enterprise environments.
Disadvantages of SOAP:
❏ Complexity: SOAP’s strict standards and XML-based messaging can be cumbersome and difficult
to work with compared to REST’s simplicity.
❏ Slower: The overhead of using XML and its verbosity makes SOAP slower and more resource-
intensive than REST.

3. GraphQL (Query Language for APIs)
❏ Origin:
❏ History: Developed internally by Facebook in 2012, GraphQL was released to the public in 2015. It
was created to address the challenges that developers faced with REST APIs, especially in terms of
over-fetching and under-fetching of data.
Key Principles:
❏ Client-driven: Unlike REST, where the server defines the structure of the response, clients using
GraphQL can specify exactly which data fields they want. This gives developers much more
flexibility.
❏ Single Endpoint: Instead of having multiple endpoints like in REST, a GraphQL API has a single
endpoint. Clients specify the structure of their query, and the server returns only the requested
data.

Key Principles:
❏ Strong Typing: GraphQL uses a schema to define the types of data it can return, and clients can
validate their queries against this schema.
How it Works:
❏ Query: The client sends a query that describes the data it needs. The query is structured like a tree,
and the server will return only the data requested.
❏ Mutation: Similar to REST’s POST, PUT, and DELETE, GraphQL uses mutations to create or update
data.
❏ Subscription: GraphQL also supports real-time data updates, making it suitable for live
applications like social feeds or live stock updates.

Advantages of GraphQL
❏ Efficient Data Fetching: Solves the problem of over-fetching and under-fetching in REST. Clients
get exactly what they need.
❏ Single Request: Unlike REST, where you might need multiple requests to different endpoints,
GraphQL can gather all the required data in one request.
❏ Real-Time Data with Subscriptions: Built-in support for real-time data updates makes it ideal for
dynamic applications.
Disadvantages of GraphQL:
❏ Complexity in Setup: GraphQL requires more setup and learning curve than REST, especially for
large applications.
❏ Overhead on Server: Since clients define what data they need, poorly written queries can put
strain on the server if they request too much data or deeply nested data structures..

Disadvantages of GraphQL:
❏ Caching Challenges: Because GraphQL allows flexible queries, caching mechanisms (like those
used in REST) are harder to implement.

SOAP REST
Early 2000s: SOAP was widely used, especially in
enterprise environments where strict security and
reliability were needed (e.g., banking, healthcare).
However, its complexity, verbose XML format, and tight
coupling made it less suitable for modern, web-based
applications.
GraphQL
Evolution of API Architectures
2015 and beyond: As applications became more complex,
especially with the rise of mobile apps and single-page
applications (SPAs), REST’s limitations became more
apparent (e.g., over-fetching and under-fetching data). This
led to the development of GraphQL, which allowed for
more efficient and flexible data fetching.
Mid-2000s: With the rise of lightweight, web-based
applications, REST gained popularity. Its simplicity,
scalability, and compatibility with the HTTP protocol made
it ideal for web services, and it quickly became the
dominant API architecture.

A timeline showing the evolution of API architectures (SOAP REST GraphQL) with key dates and milestones.
→ →

Comparison Table
Data Format
Transport Protocol
SOAP REST GraphQL
Factor
Query language for APIs
Architecture
JSON (returned data in custom structure)
Primarily HTTP
Highly flexible: Clients define the data
they need
Relies on HTTPS; needs custom security
implementations (no built-in standard like
SOAP)
Fast, but queries can become complex
and server-intensive
Architectural style (uses HTTP)
Typically JSON, but can also use XML,
HTML, etc.
Primarily HTTP
Moderate flexibility: Simple but limited by
endpoint structure
Relies on HTTPS for security, but requires
additional layers for sensitive
applications
Fast, stateless; depends on API design
Protocol (strict rules, XML-based)
XML only
Can use HTTP, SMTP, TCP, etc.
Slower due to verbose XML and
additional overhead
High-level built-in security standards
(WS-Security, encryption, signatures)
Low flexibility: Strict structure and
rules
Performance
Security
Flexibility

Comparison Table
SOAP REST GraphQL
Factor
Difficult to cache due to flexible queries
Caching
Errors returned in the response body with
partial data
Stateless, but real-time subscriptions
allow some stateful-like behaviors
No versioning needed: Schema allows for
evolution without breaking clients
High setup complexity but flexible once
configured
Built-in support for real-time data with
subscriptions
Supports caching (e.g., HTTP caching,
CDN support)
Relies on HTTP status codes (200, 404,
500, etc.)
Stateless: Each request is independent
Versioning through URL or headers
(e.g., /v1, /v2)
Moderate: Easier to use and set up than
SOAP
No native support (but can use
WebSockets)
No inherent caching mechanism
Provides detailed error messages via
the Fault element
Can support stateful operations
(through WS standards)
Complex: Versioning requires
rewriting the WSDL
High complexity: Strict rules,
verbose XML, requires WSDL
No built-in support for real-time
updates
Error Handling
Statefulness
Versioning
Complexity
Real-time Support

Comparison Table
SOAP REST GraphQL
Factor
Dynamic front-end applications, mobile
apps, and scenarios requiring custom
data fetching
Caching
Complex applications needing efficient,
flexible data queries
E-commerce platforms, social media apps
(e.g., Facebook, Shopify)
Web and mobile applications:
Lightweight services, stateless
communication, public APIs
Simple, scalable applications needing
stateless communication
Social media APIs, online stores, CRUD-
based web services
Enterprise applications requiring
high security and reliability (e.g.,
banking, healthcare)
High-security, enterprise apps that
need transactional reliability
Payment processing systems,
banking, enterprise services (ERP,
CRM)
Error Handling
Statefulness
Key Takeaways:
❏ SOAP is best for high-security, enterprise-level applications where data reliability, integrity, and security are essential.
❏ REST is ideal for simple, scalable web applications and services where performance and ease of use are key.
❏ GraphQL shines in scenarios where clients need flexible, efficient data querying, especially in mobile and dynamic web
applications.

REST API Example
❏ Retrieve All Users (GET)
❏ Endpoint : GET /users
❏ Description : The client makes a GET request to the /users endpoint to retrieve a list of all users
from the server.
❏ Example Request : https://api.example.com/users
❏ Example Output :
[
{
"id": 1,
"name": "John Doe",
"email": "john@example.com"
},
{
"id": 2,
"name": "Jane Smith",
"email": "jane@example.com"
}
]

REST API Example
❏ Create a New User (POST)
❏ Endpoint : POST /users
❏ Description : The client sends a POST request to the /users endpoint to create a new user. The
request body contains the user's details (e.g., name and email).
❏ Example Request :
POST https://api.example.com/users
Content-Type: application/json
{
"name": "Alice Johnson",
"email": "alice@example.com"
}
[
{
"id": 1,
"name": "John Doe",
"email": "john@example.com"
},
{
"id": 2,
"name": "Jane Smith",
"email": "jane@example.com"
}
]

REST API Example
❏ Update an Existing User (PUT)
❏ Endpoint : PUT /users/{id}
❏ Description : The client sends a PUT request to the /users/{id} endpoint to update an existing
user's information. The user ID is passed in the URL, and the updated details are in the request
body.
PUT https://api.example.com/users/1
Content-Type: application/json
{
"name": "John Doe",
"email": "john.doe@newexample.com"
}
{
"id": 1,
"name": "John Doe",
"email": "john.doe@newexample.com"
}

REST API Example
❏ Delete a User (DELETE)
❏ Endpoint : DELETE /users/{id}
❏ Description : The client sends a DELETE request to the /users/{id} endpoint to remove a specific
user from the system.
DELETE https://api.example.com/users/1
{
"message": "User with ID 1 has been deleted."
}

❏ GET
❏ Description:
❏ The GET method is used to retrieve data from a server. It is the most commonly used HTTP method
in RESTful APIs.
❏ Characteristics:
❏ Read-only: It doesn’t modify any data on the server.
❏ Safe and Idempotent: No matter how many times you call a GET request, it will always return the same data,
provided nothing changes on the server.
❏ Example:
❏ GET /users Retrieves the list of users.
→
❏ GET /users/123 Retrieves the details of the user with ID 123.
→
HTTP Methods in REST APIs

❏ POST
❏ Description:
❏ The POST method is used to create new resources on the server.
❏ Non-idempotent:: If you call a POST request multiple times, it will create multiple resources.
❏ Creates new data: It’s often used for submitting forms, creating new records, or uploading files.
❏ Example:
❏ POST /users
❏ Body: { "name": "John Doe", "email": "john@example.com" }
❏ Result: Creates a new user with the provided data.

❏ PUT
❏ Description:
❏ The PUT method is used to update existing resources or create a resource if it doesn’t exist. It is
typically used when updating a resource entirely.
❏ Idempotent: Calling a PUT request multiple times will result in the same resource being updated with the same
data.
❏ Replaces the entire resource: If any fields are omitted in the request body, they will be removed from the
resource.
❏ Example:
❏ PUT /users/123
❏ Body: { "name": "Jane Doe", "email": "jane@example.com" }
❏ Result: Updates the user with ID 123, replacing their details with the new ones.

❏ PATCH
❏ Description:
❏ The PATCH method is used to partially update a resource. Unlike PUT, which replaces the entire
resource, PATCH only updates specific fields.
❏ Idempotent: Like PUT, calling a PATCH request multiple times with the same data will result in the same
updates.
❏ Partial updates: You can send only the fields that need to be updated.
❏ Example:
❏ PATCH /users/123
❏ Body: { "email": "new-email@example.com" }
❏ Result: Updates the email field of the user with ID 123 without affecting other fields.

❏ DELETE
❏ Description:
❏ The DELETE method is used to remove resources from the server.
❏ Idempotent: Once a resource is deleted, calling the DELETE method again will have no effect (the resource is
already gone).
❏ Permanent action: Removes the resource entirely.
❏ Example:
❏ DELETE /users/123
❏ Result: Deletes the user with ID 123.

Benefits of Using APIs
❏ Modularity and Reusability
❏ Description : APIs promote modular development, where functionalities are encapsulated in separate components
(services, modules, etc.). This allows developers to reuse the same API across different projects, improving efficiency
and reducing redundancy.
❏ Benefit
❏ Time and cost-saving : Developers can build new applications or features faster by reusing APIs.
❏ Maintainability : Changes can be made to individual modules without affecting the entire system.
❏ Automation and Efficiency
❏ Description : APIs enable automation by allowing machines to interact with software and services directly, without
the need for human intervention. This is critical for process automation in various industries.
❏ Benefit
❏ Time and cost-saving : APIs automate repetitive tasks, reducing manual intervention and speeding up
processes.
❏ Maintainability : Businesses can integrate APIs with other tools (e.g., DevOps pipelines, CRM systems) to
streamline operations.

❏ Global Accessibility
❏ Description : APIs allow businesses to expose services or data to external developers or partners, enabling them to
build applications that work globally.
❏ Benefit
❏ 24/7 availability : APIs allow services to be available anytime, anywhere, supporting global access.
❏ Wider reach : By exposing APIs to external developers, businesses can create a broader ecosystem around their
platform.
❏ Faster Innovation
❏ Description : APIs act as building blocks for new products and services, enabling businesses to innovate faster. They
make it easier to experiment with new ideas or services by connecting them to existing infrastructure.
❏ Benefit
❏ Rapid prototyping : Developers can quickly build prototypes by leveraging external or internal APIs.
❏ Access to new markets : APIs enable the creation of new services that can be monetized, or connected to
ecosystems like app stores and partner networks.

Real-World API Examples
❏ Enhanced Collaboration
❏ Description : APIs allow different teams to work on separate parts of a system without being dependent on each
other. For example, front-end and back-end teams can work independently as long as they agree on the API contract.
❏ Benefit
❏ Parallel development : Teams can work on different services concurrently, reducing bottlenecks in the
development process.
❏ Wider reach : This decoupling makes it easier to update one part of the system without affecting the rest.
❏ Scalability
❏ Description : APIs help systems scale by allowing independent services to communicate with each other over
standardized protocols (like HTTP).
❏ Benefit
❏ Horizontal scalability : Systems can scale easily by adding more instances of API-based services without tightly
coupling them to other parts of the application.
❏ Cloud integration : APIs allow seamless integration with cloud platforms, making it easier to scale resources up
or down based on demand.

❏ Google Maps API
❏ Description : The Google Maps API allows developers to embed Google Maps on websites, mobile apps, and other
platforms. It provides access to features such as location tracking, geocoding (converting addresses into geographic
coordinates), and route planning.
❏ Use Cases
❏ Ride-hailing apps (e.g., Uber, Ola) : To show available drivers, estimated arrival times, and route navigation.
❏ Travel websites (e.g., Expedia, Airbnb) : To display locations of hotels, tourist attractions, and calculate
distances between points.
❏ Stripe API
❏ Description : The Stripe API is widely used for integrating payment processing into websites and mobile applications.
It supports a range of payment methods (credit cards, digital wallets, etc.), and it provides secure and reliable ways to
handle online transactions.
❏ Use Cases
❏ E-commerce websites (e.g., Shopify) : For secure payment processing during checkout.
❏ Subscription-based services (e.g., Netflix, Spotify) : To handle recurring payments, subscription plans, and
billing.

Conclusion
❏ APIs as Building Blocks of Modern Software: APIs (Application Programming Interfaces)
allow different software systems to communicate with each other, facilitating integration
and interaction between different platforms, applications, and services.
❏ Key Benefits
❏ Scalability : APIs make it easy to build and grow systems by allowing services to interact without
tight dependencies.
❏ Interoperability: APIs enable different systems (software programs that may be built using
different languages or frameworks) to work together seamlessly.
❏ Innovation: APIs allow developers to quickly implement new features or integrate with third-party
services, driving faster product development and innovation.

Conclusion
❏ Real-World Use Cases: We explored how APIs are used in various industries, from
payment processing with Stripe, to social media interactions with Twitter, to mapping and
location services with Google Maps.
❏ The Future of APIs: APIs will continue to evolve as the backbone of digital transformation,
enabling businesses to expand, innovate, and automate at scale. They are critical in areas
such as cloud computing, the Internet of Things (IoT), and artificial intelligence (AI).

API Development Essentials: REST, SOAP, GraphQL Explained

More Related Content

Similar to API Development Essentials: REST, SOAP, GraphQL Explained (20)

Recently uploaded (20)

API Development Essentials: REST, SOAP, GraphQL Explained

Editor's Notes