# REST API ## About REST stands for **Representational State Transfer**. It is a widely used architectural style for designing web services that allows systems to communicate over HTTP using standard methods. REST APIs are stateless, scalable, and simple to implement, which is why they are a popular choice for building modern web and mobile applications. ## What is a REST API ? A REST API is an interface that allows clients (like web browsers, mobile apps, or other servers) to interact with resources on a server using a predefined set of HTTP methods. It works by exposing endpoints (URLs) that represent resources, and each operation (like retrieving or modifying data) is performed by sending an HTTP request to one of these endpoints. For example:\ `GET /users/1` retrieves the user with ID 1.\ `POST /users` creates a new user. ## Key Components of a REST API **1. Resources** Everything in a REST API is considered a resource—users, products, orders, etc. Each resource has a unique URL (endpoint). * Example: `/users/123` represents the user with ID 123. **2. HTTP Methods (Verbs)** Each operation on a resource is performed using standard HTTP methods: * `GET` – Read data * `POST` – Create a new resource * `PUT` – Update a resource completely * `PATCH` – Update a resource partially * `DELETE` – Remove a resource **3. URI (Uniform Resource Identifier)** A URI identifies each resource. * Example: `/books/10` refers to a book with ID 10 **4. Request and Response** * **Request**: The client sends data using URL, headers, and sometimes a body. * **Response**: The server sends back data (often in JSON) with a status code. **5. Status Codes** REST APIs use standard HTTP status codes to indicate the result: * `200 OK` – Success * `201 Created` – New resource created * `400 Bad Request` – Invalid request * `404 Not Found` – Resource not found * `500 Internal Server Error` – Something failed on the server **6. Headers** Used to pass metadata like content type, authentication tokens, etc. **7. Parameters** * **Path parameters**: Included directly in the URL. Example: `/users/42` * **Query parameters**: Provide filters or options. Example: `/products?sort=price&limit=5` **8. Representation** Resources are usually represented in JSON or XML. For example, the response to `GET /user/1` might be: ```json { "id": 1, "name": "John", "email": "john@example.com" } ``` ## When to Use REST ? REST is a powerful and flexible architectural style, but it's especially effective in certain scenarios. Below are situations where using REST makes the most sense - **1. We Are Building a Resource-Oriented System** REST works best when our application deals with entities or objects that can be identified and manipulated, such as users, orders, products, or devices. If our domain is naturally organized around nouns (things), REST is a natural fit. * Example: An e-commerce platform managing products, categories, and orders. **2. We Want Simplicity and Wide Adoption** REST uses standard HTTP methods like GET, POST, PUT, and DELETE, which are familiar to most developers. It’s supported by every major programming language, framework, and toolset, so we don’t need special libraries or complex tooling to start using it. * Example: Public-facing APIs for third-party developers or teams with mixed technical backgrounds. **3. Stateless Communication Works for our Case** If our application doesn't require the server to store session state between requests (i.e., each request is independent), REST’s stateless nature makes scaling easier. Stateless APIs are easier to load-balance and distribute across servers. * Example: User profile APIs where each request includes authentication info and doesn’t rely on prior interaction. **4. We Need Caching Support** REST leverages HTTP caching mechanisms, such as ETags and Cache-Control headers, to reduce load and improve performance. This is beneficial when clients frequently request the same data. * Example: Mobile apps fetching news or weather data where updates are periodic. **5. We are Building Web or Mobile Frontends** REST is ideal for APIs consumed by frontend applications (browser or mobile) that need to retrieve and modify data on the backend. REST’s simplicity and JSON support make it frontend-friendly. * Example: A mobile app that displays user-generated content or communicates with a social media backend. **6. We Want Clear and Predictable URL Structures** REST encourages clean, readable, and predictable URIs, such as: * `/users/12/orders/50` * `/articles?category=technology` This improves API readability, documentation, and developer onboarding. **7. Interoperability Across Clients** REST APIs work over HTTP, which is universally supported. This makes it possible for any device with internet access—phones, browsers, servers, IoT devices—to use the API, regardless of language or platform. * Example: A payment service used by both a website and a mobile app. **8. We Need Loose Coupling Between Client and Server** In REST, the client and server are loosely coupled—clients don’t need to know how the server works internally, only the API contract. This allows each side to evolve independently as long as the contract is preserved. * Example: Frontend developers can continue building against a mock REST API while backend development is ongoing. **9. We Intend to Expose the API Publicly or to External Developers** REST is well-known and expected in public APIs. Its simplicity and standard behavior help third-party developers integrate easily without needing detailed instructions. * Example: Offering API access for partners or external developers to fetch user data or analytics. **10. Our Infrastructure Supports HTTP-Based Tools** Since REST uses HTTP, it plays nicely with firewalls, proxies, browsers, testing tools (like Postman), load balancers, and logging systems. This lowers operational complexity. ## When Not to Use REST ? While REST is a popular and widely used architectural style, it is **not the best fit for every situation**. Below are scenarios where using REST may introduce limitations, complexity, or inefficiency. **1. Real-Time Communication Is Needed** REST is based on request-response over HTTP. It doesn't support **server-to-client push** or real-time data updates naturally. If our application needs instant updates (e.g., chat apps, live sports scores), REST falls short. * **Better suited alternative**: WebSockets or streaming APIs using protocols like SSE (Server-Sent Events) or gRPC. **2. We Need Bi-Directional or Long-Lived Connections** In REST, the client sends a request and the server responds—it’s strictly one-way. For **long-lived, continuous, or bidirectional communication**, REST isn’t designed for that model. * **Example**: Online multiplayer games, collaborative whiteboards, or remote device control. * **Better alternative**: WebSockets or MQTT. **3. We Have Complex Workflows Not Easily Mapped to Resources** REST is ideal for resource-oriented APIs (think: things). But if our application is **action-oriented**, such as performing sequences of tasks or workflows (e.g., processing a multi-step loan application), REST becomes less natural and harder to design. * **Issue**: Actions like `approve`, `reject`, or `calculate` don't map well to standard HTTP verbs. * **Alternative**: GraphQL, RPC-style APIs, or task/event-based APIs. **4. We Need Efficient Data Fetching for Complex or Flexible Queries** In REST, we often need multiple requests to fetch related data. There’s no built-in support for specifying **exact fields or nested relationships**, which can lead to **over-fetching or under-fetching**. * **Example**: A client needs user info along with their recent orders and shipping status. * **Better alternative**: GraphQL allows clients to request exactly what they need in a single query. **5. High-Performance Requirements Over Low-Bandwidth Networks** REST uses plain text (typically JSON over HTTP), which may be **too verbose for low-bandwidth** environments like mobile networks, embedded systems, or IoT. * **Issue**: REST headers and payload sizes can be bulky. * **Alternative**: Protocol Buffers (used with gRPC), MessagePack, or binary formats. **6. We Need Strictly Defined APIs and Contract-First Development** REST lacks a universal standard for describing API contracts (though OpenAPI helps). If we require **strict schemas, validations, and auto-generated clients**, REST might feel too loose. * **Better alternative**: gRPC (uses Protocol Buffers with strict type enforcement), or tools like OpenAPI/Swagger with REST. **7. We Want to Avoid Versioning Complexity** REST APIs often require URL versioning (`/v1/products`) or header-based versioning. Managing multiple versions of endpoints can become **complex and hard to maintain**. * **Better alternative**: GraphQL (where schema evolution is built-in), or event-driven systems where versioning happens at the message level. **8. We Have Large Payloads or File Transfers** REST over HTTP may not be optimal for **streaming large files or continuous data**. File uploads/downloads can be clunky, and streaming is not native. * **Better alternative**: gRPC with streaming, or direct file transfer protocols like FTP/SFTP. **9. We Need Stronger Typing and Performance in Internal Microservices** For internal services where **performance, schema enforcement, and efficient serialization** matter more than human readability, REST may be suboptimal. * **Alternative**: gRPC or Apache Thrift for internal APIs between microservices. **10. REST Constraints Are Too Rigid for our Use Case** REST follows strict principles (statelessness, uniform interface, etc.). If these constraints are **limiting instead of helping**, such as needing stateful operations or complex custom behavior, then REST may not be worth enforcing. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://www.pranaypourkar.co.in/the-programmers-guide/api/api-styles-and-protocols/rest-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.