The aim through these system design pieces is to help the reader develop a solid grounding in applying concepts to real projects.
Once we have gathered the system requirements, we are now two steps into building our system. As mentioned earlier, the essentials of a system are inputs, outputs, and boundaries. At this point, we have our inputs and have figured our boundaries, so we build up to what we expect our output to be. We can now proceed to identify what models we will require based on what the requirements features are, how they connect, and what actions move between them.
Under entity modeling, we define the main functional elements of the system. What are the actual "things" it manages? while for API design, we define the actions and operations available on those things.
Modeling involves developing abstract models of a system, with each model presenting a different view or perspective of our system. The main objective is to understand the functionality of the system.
To understand this better, we'll need to get our hands dirty.
Exercise: Design a ToDo app.
After writing down our questions and identifying the functional and non-functional requirements as we did in the previous article, we have all the adequate information to model the system. We identify the "nouns" or the things that make up the system we are trying to build, these are our entities. We also identify the shape of these entities, what makes them up; a User has a password, username, and userID. Task has a taskID, status, and content. List has a description, a set of tasks, and a listID.
API design involves deciding what operations exist on the entities we just defined and what each hands back. It's easier to think of these as the "verbs"; function signatures: createTask(listID, contents) -> {task}, editList(listID, content) -> {list}, deleteList(listID) -> status, login(email, password) -> userID.
After we have the functional signatures, then we can translate them into an actual protocol shape.
Protocols
The common ones:
1. HTTP (Hypertext transfer protocol)
HTTP is a method for encoding and transporting data between a client and a server. It is a request/response protocol: clients issue requests and servers issue responses with relevant content and completion status info about the request. HTTP is self-contained, allowing requests and responses to flow through many intermediate routers and servers that perform load balancing, caching, encryption, and compression.
Key Characteristics
- Simple; human readable.
- Supported by all browsers.
- Stateless
Common usecase: Web browser.
2. Websockets
Websockets establish a single, persistent connection between client and server. Once it's open, either side can send data at any time.
Key Characteristics
- Bi-directional communication.
- Persistent Connection.
- Low latency
- Stateful
Common usecase: Chat applications, live dashboards, collaborative editing e.g Google Docs where realtime communication is necessary for the multiple collaborative users to edit and see changes simultaneously.
Websockets consume battery life quickly on mobile devices because they constantly ping the backend to keep the connection alive and perform handshakes. HTTP long polling can be a better middle-ground solution on mobile apps.
3. Server-sent Events (SSE)
SSE opens a single, long-lived HTTP connection over which the server streams updates to the client whenever it has something new. Data flow is strictly one way; from server to client.
Key Characteristics
- One-way communication (server to client).
- Human-readable.
Common usecase: News feeds, status updates, stock tickers i.e on stock trading dashboards.
4. gRPC
Remote Procedure Call is a framework for calling functions on a remote server as if they were local. The client and server exchange binary-encoded messages defined by a strict contract; protocol buffers, and the client/server code is generated directly from that contract.
Key Characteristics
- Binary Protocol (HTTP/2).
- Strongly-typed contracts (proto buffs -> not human readable.)
- Requires code generation.
Common usecase: Microservice communication, performance-critical systems, IoT devices.
5. REST (Representational State Transfer)
REST structures an API around resources, each identified by its own endpoint/URL and manipulated through standard HTTP verbs. It requires no technology beyond HTTP itself.
Key Characteristics
- Multiple endpoints.
- Human-readable.
- Supported by all browsers.
- Stateless.
Common usecase: CRUD apps, single sources of data, easily cached data.
6. GraphQL
GraphQL exposes a single endpoint through which clients specify exactly which fields they need and get back exactly that.
Key Characteristics
- Single endpoint.
- Precise data retrieval.
- Self-documenting API.
- Strongly typed.
Common usecase: Complex or multiple sources of data, apps supporting multiple client types, decoupling frontend from backend development.
As is common in system design, the decision on what to use is based on tradeoffs. Here's a general advice cheatsheet:
The choice between simple and complex solutions in design is guided by what's the simplest, cheapest thing you can do, rather than automatically choosing the most overengineered solution. Listing out the endpoints helps visualize the actual scope of the system.