Application Programming Interface

API stands for Application Programming Interface. It is like a bridge that allows two different software applications to communicate with each other.

Think of it as a waiter in a restaurant:

• You (the client) look at the menu (API documentation).
• You tell the waiter what you want (make a request).
• The waiter takes the order to the kitchen (server).
• The kitchen prepares the food (processes your request).
• The waiter brings the food back to you (returns a response).

So, an API defines rules and methods for how one program can request data or services from another.

API stakeholders

API stakeholders are the individuals or groups who have an interest in the development, maintenance, and use of the API. They influence or are impacted by the API at different stages of its lifecycle — from planning and design to development, testing, deployment, usage, and support.

Understanding who your stakeholders are is essential because it helps guide decisions about how the API should be designed, what features are necessary, and how it will be documented and maintained.

Major API Stakeholders

Stakeholder	Role & Interest	Example
API Consumer (Client Developer)	Uses the API to build applications. Needs clear documentation, predictable behavior, and stability.	A front-end developer integrating a payment API into a mobile app.
API Provider (Backend Developer)	Designs and implements the API. Cares about code quality, scalability, and maintainability.	A backend engineer building the endpoints for a hotel booking service.
Product Manager	Defines API requirements based on business goals and user needs. Ensures the API delivers value.	A PM deciding that the API must support search and filtering for user data.
DevOps / Infrastructure Team	Manages the deployment, availability, scalability, and monitoring of the API.	A DevOps engineer setting up auto-scaling and monitoring for API uptime.
Security Team	Ensures the API is protected from threats and data breaches. Focuses on authentication, authorization, and data encryption.	A security analyst reviewing token-based authentication and CORS policies.
QA / Testers	Verifies that the API works as expected under different conditions and handles errors properly.	A tester writing automated tests to validate REST API responses.
End User (Indirect)	May not interact with the API directly but uses applications built with it. Their feedback affects future API changes.	A customer using a food delivery app that consumes restaurant APIs.
Business Stakeholders	Focus on ROI, market fit, pricing, and competitive edge. Want the API to support business goals.	A CEO or investor looking to monetize the API via subscriptions or partnerships.

HTTP Request

1. GET

• Status Codes:
  • 200 OK: The request was successful, and the data is returned.
  • 404 Not Found: The resource was not found.

2. POST

• Status Codes:
  • 201 Created: A new resource was successfully created.
  • 400 Bad Request: Invalid input or missing parameters.

3. PUT and PATCH

• Status Codes:
  • 200 OK: The resource was updated successfully.
  • 404 Not Found: The resource was not found.
  • 400 Bad Request: The request body is not valid.

4. DELETE

• Status Codes:
  • 204 No Content: The resource was successfully deleted, and there is no content in the response body.
  • 404 Not Found: The resource to delete was not found.

HTTP Headers

Headers are extra information sent with requests and responses. They help the client and server understand each other better.

Common Request Headers

• Host → The domain of the server (e.g., Host: api.example.com)
• Authorization → Security credentials (e.g., Bearer TOKEN)
• Content-Type → Format of the body (e.g., application/json)
• User-Agent → Info about the client (e.g., Mozilla/5.0 Chrome/139)

Common Response Headers

• Content-Type → Format of response (application/json, text/html)
• Cache-Control → Tells client how long to store data before re-fetching
• Set-Cookie → Server instructs browser to save cookies (for sessions/login)

HTTP Status Codes

These are numeric codes in responses that indicate the result of the request.

Categories:

• 1xx – Informational

  Example: 100 Continue

• 2xx – Success

  • 200 OK → Request succeeded
  • 201 Created → Resource created (common for POST)
  • 204 No Content → Request succeeded but no data to return -3xx – Redirection
  • 301 Moved Permanently → Resource moved to new URL
  • 302 Found → Temporary redirect

• 4xx – Client Error

  • 400 Bad Request → Invalid request format
  • 401 Unauthorized → No/invalid authentication
  • 403 Forbidden → You don’t have permission
  • 404 Not Found → Resource doesn’t exist
  • 410 Gone → Resource removed

• 5xx – Server Error

  • 500 Internal Server Error → Generic server failure
  • 503 Service Unavailable → Server overloaded or down

Difference between REST, SOAP, and GraphQL

REST (Representational State Transfer)

• Architectural style (not a strict protocol).
• Uses HTTP methods (GET, POST, PUT, DELETE, etc.).
• Works with resources identified by URIs (/users/1).
• Responses usually in JSON (sometimes XML, HTML).
• Stateless: every request contains all needed info.

Request:

GET /users/1
Host: api.example.com

Response:

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

Best for: Simple, scalable web APIs with predictable endpoints.

SOAP (Simple Object Access Protocol)

• A protocol, not just an architectural style.
• Uses XML for both request and response.
• Strongly typed, with WSDL (Web Services Description Language) contracts.
• Supports built-in security (WS-Security) and transactions.
• More verbose and strict compared to REST.

Request (XML):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetUserRequest>
      <UserId>1</UserId>
    </GetUserRequest>
  </soap:Body>
</soap:Envelope>

Response (XML):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetUserResponse>
      <User>
        <Id>1</Id>
        <Name>Alice</Name>
        <Email>alice@example.com</Email>
      </User>
    </GetUserResponse>
  </soap:Body>
</soap:Envelope>

Best for: Enterprise systems needing high security, strict contracts, and ACID transactions (e.g., banking, telecom).

A query language for APIs (developed by Facebook).

• Client asks exactly what it needs, nothing more.
• Uses a single endpoint (/graphql).
• Schema defines available types & queries.
• Reduces over-fetching (getting too much data) and under-fetching (not enough data).

Request (GraphQL query):

{
  user(id: 1) {
    name
    email
  }
}

Response:

{
  "data": {
    "user": {
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
}

Best for: Apps needing flexibility (e.g., mobile apps where bandwidth matters) or when multiple resources need to be fetched in one request.

REST vs SOAP vs GraphQL (Comparison Table)

Feature	REST 🌐	SOAP 📦	GraphQL 🔍
Type	Architectural style	Protocol	Query language
Data format	JSON, XML, HTML	XML only	JSON
Endpoint structure	Multiple endpoints (/users, /posts)	Single endpoint (defined in WSDL)	Single endpoint (/graphql)
Flexibility in data fetching	Limited (fixed response structure)	Strict (fixed XML schema)	High (client chooses fields)
Performance	Can cause over/under-fetching	Verbose, heavy payloads	Optimized, single request
Security	Relies on HTTPS & tokens	Built-in WS-Security	Relies on HTTPS & custom
Use case	General web APIs	Enterprise, banking, legacy systems	Modern apps (web/mobile) needing flexibility

Idempotent vs Non-Idempotent Methods

Idempotent

A method is idempotent if making the same request multiple times has the same effect on the server as making it once.

• The result on the server doesn’t change no matter how many times you repeat it.
• The response might differ (like different timestamps), but the state of the resource remains the same.

Non-Idempotent

A method is non-idempotent if making the same request multiple times causes a different result on the server.

• Repeating the request changes the server state each time.

Idempotent vs Non-Idempotent (Comparison Table)

Method	Idempotent?	Why
GET	✅ Yes	Just retrieves data, no change
POST	❌ No	Creates new resource each time
PUT	✅ Yes	Replaces resource completely (same result)
PATCH	✅ Yes (usually)	Same update applied repeatedly → same result
DELETE	✅ Yes	Resource is deleted, repeating doesn’t change outcome