Consuming REST APIs: Speaking to Web Services

WHY IT EXISTS: REST was created to provide a standard, predictable way for different software systems to communicate over the web. It defines a set of rules, or constraints, that allow a client (like a mobile app) and a server to talk to each other without needing to know the messy details of each other's internal code. This promotes a "uniform interface" for the entire web.

THE MENTAL MODEL: An analogy is ordering from a restaurant. The URL is the restaurant's address. The endpoint, like /users/123, is a specific item on the menu. The HTTP verb (GET, POST, PUT, DELETE) is your action: "I want to GET this item," "I want to POST a new order," or "I want to DELETE my order." The server's response, often in a format like JSON, is the food delivered to your table. The HTTP status code (200 OK, 404 Not Found) is the waiter telling you if your order succeeded.

HOW IT WORKS: A client application constructs an HTTP request. This request has a few key parts. First, an HTTP method or verb that defines the action (e.g., GET to retrieve data). Second, a URL that identifies the resource you want to interact with (e.g., https://api.example.com/v1/articles/42). Third, headers, which contain metadata like authentication keys or the format you accept for the response. Fourth, an optional body, which contains data you're sending to the server, typically used with POST or PUT requests to create or update a resource. The server receives this, performs the action, and sends back an HTTP response containing a status code and, usually, a body with the requested data or the result of the action.

WHEN TO USE IT: You consume a REST API whenever you need your application to communicate with a remote service over HTTP. This is the dominant architectural style for public web APIs, used for everything from fetching data from social media platforms, getting financial market data, or connecting your frontend application to your backend microservices. Its stateless nature makes it highly scalable.

WHEN NOT TO USE IT: REST is not the best choice for all scenarios. For real-time, continuous communication like in a chat application or a live-updating game, technologies like WebSockets are more suitable. For complex data queries where the client needs to specify exactly which fields to return to avoid over-fetching, GraphQL can be a more efficient alternative.

ONE CANONICAL EXAMPLE: To fetch a user profile with ID 42 from a service, your code would send an HTTP GET request to an endpoint like https://api.example.com/users/42. The server would ideally respond with a 200 OK status code and a JSON body containing the user's data, such as { "id": 42, "name": "Ada Lovelace", "email": "ada@example.com" }. If the user didn't exist, it would return a 404 Not Found status code.