Restful API mostly asked interview questions

RESTful web services are web services that follow the principles of REST (Representational State Transfer) to enable simple, scalable, and stateless communication between client and server over HTTP.

They expose resources (data or functionality) through URLs and use standard HTTP methods like GET, POST, PUT, PATCH, and DELETE to perform operations on those resources.

REST is a lightweight architectural style that uses HTTP and usually JSON, making it fast and scalable, while SOAP is a strict XML-based protocol with built-in security and standards, mainly used in enterprise systems.

REST is better for performance and scalability, while SOAP is better for strict security and transactions.

REST mainly uses HTTP methods like GET, POST, PUT, DELETE, PATCH, and OPTIONS to perform operations on resources. GET fetches data, POST creates, PUT replaces, PATCH partially updates, DELETE removes resources, and OPTIONS checks supported operations.

In RESTful APIs, a resource is any piece of data or object that can be identified by a unique URI and manipulated using HTTP methods.

Easy Examples of Resources

• User
• Order
• Product
• Payment

In REST, each request contains all required information. The server does not store client session state, improving scalability and reliability.

A URI (Uniform Resource Identifier) uniquely identifies a resource.

Example:

GET /api/orders/500

GET /api/orders/500

URIs represent nouns, not actions.

Safe methods never modify data, while idempotent methods can modify data but produce the same result when called multiple times. GET is safe because it never modifies data, and idempotent because multiple calls produce the same result.

Safe methods: Do not modify data

• GET, HEAD, OPTIONS

Idempotent methods: Same result on repeated calls

• GET, PUT, DELETE

Example: Multiple DELETE calls → resource still deleted.

Most Common Status Codes (Must-Know)

2xx – Success

• 200 OK → Request successful
• 201 Created → Resource created successfully
• 204 No Content → Success, but no response body

4xx – Client Errors

• 400 Bad Request → Invalid request data
• 401 Unauthorized → Authentication required
• 403 Forbidden → Access denied
• 404 Not Found → Resource not found
• 409 Conflict → Duplicate or conflicting request

5xx – Server Errors

• 503 Service Unavailable → Server temporarily unavailable
• 500 Internal Server Error → Generic server failure
• 502 Bad Gateway → Invalid response from upstream server

HATEOAS (Hypermedia As The Engine Of Application State) means the API response includes links to related actions/resources.

Importance:

• Enables easier evolution of APIs without breaking clients
• Reduces client–server coupling
• Makes APIs self-discoverable

A request is idempotent if multiple identical requests produce the same result.

Example:

• POST → not idempotent
• PUT, DELETE → idempotent

Content negotiation allows the client and server to agree on the response format.

• Client uses Accept header
• Server responds with supported format (JSON, XML)

Example:

Accept: application/json

Accept: application/json

Common strategies:

• URI versioning: /api/v1/users
• Header versioning: Accept: application/vnd.app.v1+json
• Query parameter: /users?version=1

URI versioning is the most commonly used and simplest.

Caching stores responses to avoid repeated processing.

Implementation:

• Client-side, proxy, or CDN caching
• HTTP headers: Cache-Control, Expires
• Conditional requests using ETag and If-None-Match

Pagination divides large datasets into smaller chunks.

Implementation methods:

• Cursor-based pagination for large datasets
• Query parameters: ?page=1&size=10
• Offset-limit: ?offset=20&limit=10

ETags (Entity Tags) are unique identifiers for a resource version that help browsers and clients cache responses and avoid downloading unchanged data. ETags allow clients to cache responses efficiently by validating whether a resource has changed before fetching it again.

An API version deprecation strategy is a planned approach to retire old API versions safely while giving clients time to migrate to newer versions without breaking their applications. API version deprecation ensures backward compatibility while smoothly transitioning clients to newer versions.

• Use plural nouns for collections (/users)
• Avoid verbs (/createUser ❌)
• Use hierarchical relationships where needed:

/users/{userId}/orders

/users/{userId}/orders

• Use kebab-case or lowercase consistently
• Avoid implementation details in URIs

API documentation is a guide that explains how to use an API, including its endpoints, request/response formats, parameters, and error codes. API documentation is maintained by updating it whenever the API changes.

What API Documentation Contains

• API endpoints (URLs)
• HTTP methods (GET, POST, etc.)
• Request parameters & headers
• Request/response examples
• Status codes & error messages
• Authentication details

Common API error response patterns provide a consistent JSON structure with an error code, message, and details so clients can easily understand and handle failures.

Most Common Error Response Patterns

1. Standard JSON Error Object (Most Used)

{
  "timestamp": "2026-02-10T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid email format",
  "path": "/api/users"
}

{
  "timestamp": "2026-02-10T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid email format",
  "path": "/api/users"
}

✔ Easy to read
✔ Widely used in REST APIs

2. Error Code + Message Pattern

{
  "errorCode": "USER_001",
  "errorMessage": "User not found"
}

{
  "errorCode": "USER_001",
  "errorMessage": "User not found"
}

✔ Machine-friendly
✔ Easy for frontend mapping

3. Validation Error Pattern

{
  "errors": [
    {
      "field": "email",
      "message": "Email is invalid"
    }
  ]
}

{
  "errors": [
    {
      "field": "email",
      "message": "Email is invalid"
    }
  ]
}

✔ Best for form validations
✔ Clear field-level errors

4. RFC 7807 – Problem Details (Standard)

{
  "type": "https://example.com/errors/invalid-input",
  "title": "Invalid input",
  "status": 400,
  "detail": "Email format is incorrect"
}

{
  "type": "https://example.com/errors/invalid-input",
  "title": "Invalid input",
  "status": 400,
  "detail": "Email format is incorrect"
}

✔ Standardized
✔ Used in modern APIs

API deprecation is the process of phasing out an old API version without breaking existing clients.

Best practices to handle API deprecation:

1. Gradually remove deprecated APIs
   After the sunset period, remove the old version safely.
2. Announce deprecation early
   Clearly mark the API as deprecated in documentation and communicate timelines to consumers.
3. Version your APIs
   Introduce breaking changes in a new version (e.g., /api/v2) while keeping /api/v1 operational.
4. Use deprecation headers
   Include HTTP headers like: Deprecation: true Sunset: Wed, 30 Jun 2026 23:59:59 GMT to inform clients programmatically.
5. Maintain backward compatibility temporarily
   Continue supporting the old version for a defined grace period.
6. Provide migration guides
   Document changes and offer examples to help clients upgrade smoothly.
7. Monitor deprecated API usage
   Log and track which clients still use deprecated endpoints.

An API Gateway acts as a single entry point between clients and backend services (usually microservices).

High-level working flow:

High-level working flow:

1. Client sends request
   The client (web, mobile, third-party app) sends all API requests to the API Gateway instead of directly to services.
2. Request validation & security
   The gateway handles:
   • Authentication (JWT, OAuth2, API keys)
   • Authorization
   • SSL termination
3. Traffic control
   It applies:
   • Rate limiting & throttling
   • Request size limits
   • IP filtering
4. Routing & load balancing
   The gateway forwards the request to the appropriate backend service and may load-balance across multiple instances.
5. Cross-cutting concerns
   Centralized handling of:
   • Logging and monitoring
   • Caching
   • Request/response transformation
6. Response aggregation (optional)
   Combines responses from multiple microservices into a single response for the client.
7. Response sent back to client
   The gateway returns the final response to the client.

API throttling is a technique used to limit the number of requests a client can make to an API within a specified time window.

Why API throttling is needed

• Prevents API abuse and DDoS attacks
• Protects backend services from overload
• Ensures fair usage among clients
• Improves overall system stability and performance

How API throttling works (high level)

1. Client sends requests to the API
2. Throttling rules are checked (per user, IP, API key)
3. If the limit is exceeded:
   • Request is rejected with HTTP 429 (Too Many Requests)
4. If within limit:
   • Request is forwarded to the backend service

Key principles for designing backward-compatible APIs

1. Never break existing contracts
   Do not remove or rename existing fields, endpoints, or status codes.
2. Additive changes only
   • Add new fields instead of modifying old ones
   • Ensure new fields are optional
   • Provide default values
3. Preserve response formats
   Keep existing JSON structure intact and avoid changing data types.
4. Use API versioning for breaking changes
   Introduce /v2 for incompatible changes while maintaining /v1.
5. Tolerant readers
   Design clients to ignore unknown fields in responses.
6. Maintain semantic consistency
   Avoid changing the meaning of existing fields or behavior.
7. Deprecate gracefully
   Mark features as deprecated and provide migration paths before removal.

Testing REST APIs ensures that the APIs are correct, reliable, secure, and scalable. It is usually done at multiple levels using different tools.

Testing methods

1. Unit Testing

• Tests individual components like controllers and services in isolation
• Focuses on request handling, validation, and response structure

Tools:

• JUnit
• Mockito
• Spring @WebMvcTest, MockMvc

2. Integration Testing

• Tests API behavior with real dependencies (database, message queues, security)
• Verifies request-to-response flow

Tools:

• Spring Boot @SpringBootTest
• REST Assured
• Testcontainers

3. End-to-End (E2E) Testing

• Tests the complete system as a client would use it
• Covers authentication, authorization, and data flow

Tools:

• Postman
• Newman
• Curl

4. Contract Testing

• Ensures API implementation matches the agreed contract between services
• Prevents breaking changes

Tools:

• Spring Cloud Contract
• Pact

5. Performance & Load Testing

• Validates API behavior under high traffic
• Measures response time and throughput

Tools:

• JMeter
• Gatling
• k6
• Locust

Common testing tools

• Postman – Manual testing and automation
• Swagger UI (OpenAPI) – Interactive testing + documentation
• REST Assured – Java-based API testing
• Curl – Quick command-line testing

Postman and Swagger are commonly used together, Swagger for documentation and exploration, and Postman for testing and automation.

Using Swagger (OpenAPI)

Purpose: API documentation + interactive testing

How it is used:

• Define APIs using OpenAPI specification
• Automatically generate interactive documentation
• Test APIs directly from the browser
• Keeps documentation in sync with code

What it documents:

• Endpoints and HTTP methods
• Request/response models
• Status codes
• Authentication methods

Benefit:
Provides a single source of truth for API consumers.

Using Postman

Purpose: Manual and automated API testing

How it is used:

• Send HTTP requests (GET, POST, PUT, DELETE)
• Validate responses, headers, and status codes
• Write test scripts using JavaScript
• Organize APIs into collections
• Automate tests using Newman (CLI)

Benefit:
Helps in functional, regression, and integration testing.

A mock server is a simulated server that mimics the behavior of a real API by returning predefined responses without calling the actual backend.

Why mock servers are used

Mock servers are mainly used when:

• Backend APIs are not ready yet
• Third-party APIs are unavailable, slow, or costly
• Teams want to test edge cases and failures
• Frontend and backend teams work independently

How mock servers work (high-level)

1. Client sends a request to the mock server
2. Mock server matches the request (URL, method, headers)
3. Returns a predefined response (JSON, status code, headers)
4. No real business logic or database is involved

Popular mock server tools

• Postman Mock Servers
• WireMock (very common in Spring Boot testing)
• MockServer
• JSON Server (lightweight)

Load testing is the process of evaluating how a REST API performs under expected and peak traffic conditions by sending a large number of concurrent requests.

Why load testing is important

• Ensures the API can handle real-world traffic
• Identifies performance bottlenecks (CPU, memory, DB, network)
• Validates scalability and stability
• Prevents production outages

Common load testing tools

• JMeter
• Gatling
• k6
• Locust

Types of performance testing

• Load testing – Expected traffic
• Stress testing – Beyond capacity
• Spike testing – Sudden traffic surge
• Soak testing – Long-duration load