Design a Comment Service

Comment service API: Overview and architecture

Social media platforms enable users to comment on posts, providing feedback, corrections, or appreciation. Behind this seemingly simple interaction is a complex system of interacting components. The API that interlinks these components must handle client requests through an API gateway, which acts as a reverse proxyA reverse proxy sits at the edge of the applications backend. Its main job is to direct client requests to one of many application/origin servers. Reverse proxies provide a layer of security to backend servers by hiding their identity., routing requests to backend services while enforcing authorization, access control, caching, and throttling. After processing succeeds or fails, a response propagates back to the client.

Requirements

Functional requirements

The API must support these operations:

• Create a comment: Post a new comment on a resource.

• Update a comment: Edit a previously posted comment.

• Get comment(s): Fetch one or more comments from backend servers.

• Delete a comment: Remove a posted comment.

• Flag comments: Any user can flag a comment that violates the platform's code of conduct.

Note: For simplicity, we refer to a resource where comments are posted as a "post." Our design considers only comments on public resources.

Nonfunctional requirements

• Scalability: Handle an ever-increasing number of users commenting across posts.

• Availability: Provide continuous, uninterrupted service.

• Security: Enforce modern authorization/authentication and secure client-server communication.

• Reliability: Operate correctly despite partial system failures.

• Low latency: Serve publicly posted comments with minimal delay.

With these requirements established, the design proceeds through three phases: key design decisions (architecture style, data format, HTTP version), the concrete API model (endpoints and message formats), and, finally, an evaluation against nonfunctional requirements, including a latency budget.

Design overview and decisions

API design depends not only on organizational requirements but also on the system's internal architecture. All client requests pass through the API gateway and fan out to multiple backend services. When the backend receives a comment for a post, it sets various attributes, appends the comment to the relevant post, and persists it to the database. Update and delete requests follow a similar flow.

For brevity, the comment service handles only text content. The following table describes the essential components involved in the comment service design.

Workflow

Client requests pass through the API gateway, which performs identity and access management. After successful verification, the gateway routes requests to the comment service. This service consults the user service to validate user information and the posts service to resolve the target post. The comment is then created and stored with relevant user and post metadata. The key architectural question is which style governs communication between the client, the API gateway, and backend services.

Design considerations

The following are the design considerations for the comment service.

Architecture styles

Client to API gateway

Comment operations map directly to CRUDCreate, read, update, delete., making REST a natural fit for client-to-gateway communication without introducing unnecessary complexity.

API gateway to backend services

• REST: Provides standardized CRUD operations for structured resources (comments) and is simpler than alternatives, making it a strong candidate.

• GraphQL: Better suited for ...