REST and GraphQL

You are here because you need to understand how two pieces of software talk to each other over the internet. REST and GraphQL are the two most common ways to build that conversation. Mastering this unlocks: reading and writing your own API endpoints, understanding how a frontend (a mobile app or a browser page) fetches data from a backend server, debugging 'why is this request 404' and 'why is this response so slow', and making architectural decisions about which style to use for a new system. Later, when you work with AI, you will call APIs constantly — to send data to a model or to get results back — and knowing what is happening inside those API calls will separate you from someone who just copies code. This concept is the doorway to your future work with real systems, so it is the last pure software concept you need before you start building things that touch AI services.

Think of two people trying to exchange information. There is a request — the asker says something — and there is a response — the other person answers. REST and GraphQL are two different sets of rules for how that ask and answer work over the internet. The word 'API' just means the agreed set of rules. A restaurant menu is an API: the kitchen has decided that if you say 'chicken curry' you get chicken curry, but if you say 'pass me the salt' they won't look at you. Similarly, a server has decided what requests it responds to and what each response looks like. REST is like ordering from a fixed menu: the menu lists dishes, you pick one, and you get a standard plate. You cannot ask for 'chicken without the onions, extra rice, but only the left half' — the kitchen has pre-defined the dishes, and if you want something slightly different you must order a different dish or accept what comes. GraphQL is like going to a buffet where you can say 'give me the chicken, but only the dark meat, and half the rice' and the server plate is exactly what you asked for, nothing more, nothing less. Both get you food, but the experience and the flexibility differ. On the internet, the 'dish' in REST is a resource — a user, a product, a post. The 'menu' is a set of addresses called URLs, and you use standard verbs like GET (look at the menu) or POST (order something) to interact. GraphQL has no such fixed menu; it has a single address, and you send a question describing exactly the shape of the answer you want. So the intuition: REST is about getting the whole thing; GraphQL is about asking for exactly the pieces you need.

Imagine you want to buy a book at a large bookshop. The book is a resource. In REST, you go to the counter and say 'I want book number 12345' (a URL) and the clerk hands you the entire book — cover, all pages, even the blank ones. If you only wanted one chapter, you still receive the whole thing, because the shop has decided that the unit of exchange is the book. Now suppose you wanted just the price and the author's name — in REST you still get the whole book or you need a different 'edition' (a different URL that gives a smaller version, but that version is still pre-defined). That is exactly what happens: a server often returns a big JSON object with many fields, and the client has to filter out what it doesn't need. In GraphQL, instead of going to the counter, you go to a special order desk. You write a note: 'Give me the price and the author's name for book 12345, and also the first paragraph of the first chapter' — and the desk returns only those bits, neatly put together. The bookshop hasn't given you the whole book; they've efficiently extracted what you asked for. The catch: the bookshop has to have a special system to understand your note. The counter works for everybody, but the order desk needs a manual that explains all possible combinations — this is the 'schema'. Where the analogy stops working: in a real bookshop, the order desk would be a human who knows the shop's inventory. In software, GraphQL still needs a server that has all the data available, so the request may have to fetch several different data sources behind the scenes. Also, REST can give you exactly what you want if the designer of the API has created the right endpoint; the problem is that you (the client) cannot change the server's menu. GraphQL gives the client flexibility, but it moves the work to the server — the server must be able to parse the query and fetch the data efficiently. In a bookshop, the clerk can retrieve a whole book faster than they can assemble a custom package from different shelves.

REST is an API style where a server organizes its data into resources identified by URLs, and clients use standard HTTP methods (like GET, POST, PUT, DELETE) to perform operations on those resources, always receiving a fixed, pre-defined representation. GraphQL is a query language and runtime that lets a client send a nested query describing exactly which fields and which combined data it wants, and the server responds with precisely that structure.

You already know from your notes on Software Architecture that the way components communicate is an architectural decision that is expensive to reverse. Choosing between REST and GraphQL is exactly such a decision: you are choosing the boundary between your client and your server, and the dependency direction (the client depends on the server's interface). Your notes on Cohesion and Coupling apply here: a REST API with a well-chosen set of resources has high cohesion (each resource is a focused unit), while a GraphQL schema can become a giant grab-bag if not carefully shaped, lowering cohesion. Tight coupling between client and server is what GraphQL tries to break by letting the client request exactly what it needs, but it does so by introducing a shared schema that both sides must agree on — a different form of coupling. Your notes on Dependency Inversion are relevant: the client should depend on the API's interface (the schema in GraphQL, the resource descriptions in REST) rather than on a concrete implementation. Both styles are 'ports' and 'adapters' in hexagonal architecture: the API is the port, and the HTTP implementation is the adapter.